@dsivd/prestations-ng 19.1.2 → 19.2.0-beta.10

package/UPGRADING_V18.md

@@ -458,6 +458,7 @@ npm install @angular/cli@19 -g
 ng update typescript@5.5
 ng update @dsivd/prestations-ng@18
 ```
+
 NB: You might need to use the --force option.
 
 When asked the question "Select the migrations that you'd like to run", accept "provide-initializer" by hitting "Space" key then "Enter".

package/UPGRADING_V19.md

@@ -11,6 +11,9 @@ From here on, we are in the root folder of your project, for example ~/git/cybsd
 
 ### Spring Boot 4
 
+NB : if the following instructions (jdk25 + latest parent + openrewrite) are not working fine, you can also try to
+do in the reverse order : in jdk21 do the rewrite commands, then switch to jdk25 and latest parent.
+
 You can switch to Java 25 `jdk25` + change in IntelliJ: right-click on your project > Open Module Settings > Project > set "SDK" to `jdk25` from devtools and "Language
 level" to `25` in "Modules"
 
@@ -78,6 +81,17 @@ if you use ldap, you should replace `spring-ldap-core` by `spring-boot-starter-l
 </dependency>
 ```
 
+### ORACLE
+
+if you use oracle, you should replace `ojdbc10` by `ojdbc17` in your `pom.xml` and let the spring boot parent set the version
+
+```xml
+<dependency>
+    <groupId>com.oracle.database.jdbc</groupId>
+    <artifactId>ojdbc17</artifactId>
+</dependency>
+```
+
 ### Jackson migration
 
 With Spring Boot 4, Jackson 3 is now used instead of Jackson 2, so we need to replace the previous Jackson 2 classes.
@@ -857,7 +871,7 @@ ng generate @angular/core:signal-input-migration --insert-todos
 [Angular migration guide: migrating to Vitest](https://angular.dev/guide/testing/migrating-to-vitest)
 
 ```bash
-npm install --save-dev vitest jsdom
+npm install --save-dev vitest@4.0 jsdom
 ```
 
 In your `angular.json` file, remove `"zone.js/dist/zone-error"` from `"allowedCommonJsDependencies"`
@@ -1050,6 +1064,8 @@ npm install --save-dev eslint-plugin-simple-import-sort@13
 npm install --save-dev eslint-config-prettier@10
 npm install --save-dev eslint-plugin-import-x@4
 npm install --save-dev prettier
+# only if your project has Vitest specs (see "Migrate to vitest")
+npm install --save-dev @vitest/eslint-plugin@1
 ```
 
 In your `front` folder, add a `.prettierrc` file with the following content:
@@ -1126,6 +1142,12 @@ export default tseslint.config(
         extends: [...prestationsNg.configs.templateRecommended],
     },
 
+    // ─── Vitest specs (only if your project has Vitest specs) ─────────────────
+    {
+        files: ['**/*.spec.ts'],
+        extends: [...prestationsNg.configs.specTsRecommended],
+    },
+
     // ─── Prettier (must be last — disables formatting rules) ───────────────────
     prettier,
 );
@@ -1136,6 +1158,11 @@ everything: the `eslint`, `typescript-eslint` and `angular-eslint` baselines, th
 accessibility set, the naming and import conventions, and the rules written by the library
 itself. You declare no `plugins` and list no rule.
 
+`specTsRecommended` is the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions
+made by the `HttpTestingController` (`expectOne`, `expectNone`, `verify`) and by helpers named `expect*`,
+`assert*` or `test*`. The `**/*.spec.ts` pattern does not reach the Cypress `*.spec.cy.ts` files. It needs
+`@vitest/eslint-plugin` only when you use it: the other configs work without it.
+
 The packages installed above are still required — the library's config imports them from your
 `node_modules` rather than shipping its own copies. For the same reason, do **not** spread
 `angular.configs.tsRecommended` or `angular.configs.templateRecommended` yourself: they are
@@ -1396,7 +1423,7 @@ npm uninstall @angular/animations
 
 ### Add missing `^` or `~` in `package.json` devDependencies
 
-Check you devDependencies in your `package.json` file and add `^` in front of every version number if missing excepted for `typescript` where you should add `~`. Then run:
+Check you devDependencies in your `package.json` file and add `^` in front of every version number if missing excepted for `typescript` and `vitest` where you should add `~`. Then run:
 
 ```bash
 npm install
@@ -1416,6 +1443,191 @@ When using `IntelliJ`, you can run code inspection on your project to fix deprec
 - IntelliJ window menu, go to: `Code > Analyze code > Run inspection by name...` (or **Ctrl+Alt+Maj+i**) and type `Deprecated symbol used`.
 - 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`.
 
+### Strict mode (optional when migrating large projects but recommended)
+
+- 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.
+- In your `tsconfig.json` file, remove `useDefineForClassFields` from `compilerOptions`.
+
+Now fix your project until no more errors:
+
+```bash
+npx tsc -b --noEmit
+```
+
+and finally run the following commands to build, test and start your application:
+
+```bash
+npm run build
+npm run test
+npm start
+```
+
+### `foehn-list-summary` is now generic (since 19.2.0)
+
+`FoehnListSummaryComponent` is now `FoehnListSummaryComponent<T extends FoehnListItem>` and `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
+Using `FoehnListItemDescription` without its type parameter no longer compiles.
+
+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`:
+
+Before:
+
+```typescript
+getListItemsDescription(): FoehnListItemDescription[] {
+    return [
+        {
+            label: 'Name',
+            getFormattedValue: (item: FoehnListItem) =>
+                (item as MyItem).name ?? '',
+        },
+    ];
+}
+```
+
+After:
+
+```typescript
+getListItemsDescription(): FoehnListItemDescription<MyItem>[] {
+    return [
+        {
+            label: 'Name',
+            getFormattedValue: (item: MyItem) => item.name ?? '',
+        },
+    ];
+}
+```
+
+The same applies to the function passed to `getListItemTitle`, which now receives a `MyItem`.
+
+### `core-js` is no longer needed (since 19.2.0)
+
+prestations-ng no longer imports `core-js` and no longer has it as a peer dependency. If your project does not
+import `core-js` itself, uninstall it:
+
+```bash
+npm uninstall core-js
+```
+
+Then, in your `angular.json` file, remove `"core-js/modules/es.array.includes"` from `"allowedCommonJsDependencies"`.
+The CommonJS dependencies of prestations-ng are now `"iban"` and `"dayjs"` (which also covers `dayjs/plugin/*` and
+`dayjs/locale/*`):
+
+```json
+"allowedCommonJsDependencies": ["iban", "dayjs"]
+```
+
+### Zoneless (optional but recommended)
+
+Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
+tell Angular when a component has to be refreshed. prestations-ng keeps working in an application using zone.js,
+so this step is optional, but a zoneless application is lighter, faster and easier to debug. See the
+[Angular zoneless guide](https://angular.dev/guide/zoneless).
+
+In any case, if your code reads some fields of the prestations-ng components (e.g. through `viewChild()` or in
+your tests), check the fields that are now signals in the [CHANGELOG](CHANGELOG.md#1920---should-be-aligned-with-prestations-be-192x).
+
+#### Enable the zoneless change detection
+
+Zoneless is the default since Angular 21: `ng update` added `provideZoneChangeDetection()` to keep zone.js in your
+application. Replace it in your `app.config.ts` (`providePrestationsNgCore()` already provides
+`provideBrowserGlobalErrorListeners()`, which reports to your `ErrorHandler` the errors zone.js used to catch):
+
+```diff
+export const appConfig: ApplicationConfig = {
+    providers: [
+-       provideZoneChangeDetection({ eventCoalescing: true }),
++       provideZonelessChangeDetection(),
+        providePrestationsNgCore(),
+        ...
+    ],
+};
+```
+
+Remove `zone.js` and `zone.js/testing` from the `polyfills` of the `build` and `test` targets in your
+`angular.json` (and from your `polyfills.ts` file if you still have one): without them, the `TestBed` is zoneless
+too.
+
+```diff
+"polyfills": [
+-   "zone.js"
+],
+```
+
+then uninstall zone.js:
+
+```bash
+npm uninstall zone.js
+```
+
+#### Check your components
+
+Without zone.js, Angular refreshes a component only when it is notified that something changed:
+
+- a listener of its template has been called (`(click)`, `(modelChange)`, `(userInput)`...), including the
+  `[(model)]` two-way bindings
+- a signal read by its template has changed (`signal()`, `computed()`, `input()`, `model()`, `toSignal()`...)
+- `ChangeDetectorRef.markForCheck()` has been called, which is what the `async` pipe does when an observable emits
+
+A field modified elsewhere (in a `subscribe()`, a `setTimeout()`, a `Promise`, a callback...) is not displayed
+anymore until something else refreshes the component. Hold it in a signal (see
+[INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md)):
+
+```diff
+- isLoading = true;
++ readonly isLoading = signal(true);
+
+  ngOnInit(): void {
+      this.myService.load().subscribe(() => {
+-         this.isLoading = false;
++         this.isLoading.set(false);
+      });
+  }
+```
+
+```diff
+- @if (isLoading) {
++ @if (isLoading()) {
+```
+
+Pay attention to:
+
+- your pages (`AbstractPageComponent` and its subclasses): prestations-ng refreshes them when it sets `form` and
+  `reference`. But if you modify the form yourself in an asynchronous callback, e.g. the one given to
+  `SessionInfoWithApplicationService.prefillForm()` or a `subscribe()` of your own service, call
+  `markForCheck()` afterwards:
+
+    ```ts
+    private readonly changeDetectorRef = inject(ChangeDetectorRef);
+
+    ngOnInit(): void {
+        super.ngOnInit();
+        this.sessionInfoWithApplicationService.prefillForm((info) => {
+            this.form.email = info?.email ?? null;
+            this.changeDetectorRef.markForCheck();
+        });
+    }
+    ```
+
+- `NgZone`: `onStable`, `onMicrotaskEmpty` and `onUnstable` never emit without zone.js, and `run()` or
+  `runOutsideAngular()` are useless. To act on the rendered DOM (focus, scroll...), replace them, as well as the
+  `setTimeout()` waiting for the view, by `afterNextRender()`. `AbstractMenuPageComponent.ngZone` is deprecated.
+
+    ```diff
+    - this.ngZone.onStable.pipe(first()).subscribe(() => this.focusFirstField());
+    + afterNextRender(() => this.focusFirstField(), { injector: this.injector });
+    ```
+
+#### Check your tests
+
+- `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` need zone.js: write `async` tests, with
+  `vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)` to control the timers (see
+  [Migrate to vitest](#migrate-to-vitest)).
+- `fixture.detectChanges()` only refreshes the views which have been notified, then checks that nothing changed
+  meanwhile: a field modified without notification makes the test fail with the error `NG0100`
+  (`ExpressionChangedAfterItHasBeenCheckedError`). Fix the component (signal, `markForCheck()`) rather than the
+  test.
+- `await fixture.whenStable()` waits for the change detection and for the pending tasks of the application
+  (e.g. the debounced `userInput` of the prestations-ng inputs), not for the timers.
+
 ### Last but not least, check if your application is working!!!
 
 #### Be sure your application gets a fresh start
@@ -1455,7 +1667,8 @@ See [getImtPortailApplications](https://dsigit.etat-de-vaud.ch/outils/git/projec
         'project': 'cybersdk',
         'name'   : 'skeleton',
         'gitUrl' : 'ssh://git@bitbucket.etat-de-vaud.ch/cybsdk/skeleton.git',
-        'jdk'    : '21',
+-       'jdk'    : '21',
++       'jdk'    : '25',
 -       'node'   : '20'
 +       'node'   : '22'
 ],
@@ -1465,3 +1678,11 @@ See [getImtPortailApplications](https://dsigit.etat-de-vaud.ch/outils/git/projec
 
 Enroll your project in Renovate bot to automatically update your dependencies.
 See [Mend Renovate CE](https://dgnsiwiki.etat-de-vaud.ch/outils/dgnsiwiki/x/7QFDgg) for more information.
+
+update renovate.json :
+
+```json
+{
+    "extends": ["local>PEE/renovate-config"]
+}
+```

package/eslint/configs/spec-ts-recommended.mjs

@@ -0,0 +1,34 @@
+/**
+ * The house preset of the Vitest specs: the recommended rules of `@vitest/eslint-plugin`, with the
+ * assertions also made by the helpers of the specs and by the `HttpTestingController`.
+ *
+ * Meant for the `extends` of a `**\/*.spec.ts` block (the Cypress `*.spec.cy.ts` files are not
+ * Vitest specs).
+ *
+ * @param {import('@vitest/eslint-plugin').default} vitest the `@vitest/eslint-plugin` module
+ * @returns {import('typescript-eslint').ConfigArray}
+ */
+const specTsRecommended = (vitest) => [
+    vitest.configs.recommended,
+    {
+        name: 'prestations-ng/spec-ts-recommended',
+        rules: {
+            'vitest/expect-expect': [
+                'error',
+                {
+                    assertFunctionNames: [
+                        'expect',
+                        'expect*',
+                        'assert*',
+                        'test*',
+                        '*.expectOne',
+                        '*.expectNone',
+                        '*.verify',
+                    ],
+                },
+            ],
+        },
+    },
+];
+
+export default specTsRecommended;

package/eslint/configs/template-recommended.mjs

@@ -8,6 +8,8 @@ import templateRules from './template-rules.mjs';
  *
  * Meant for the `extends` of a `**\/*.html` block. It brings its own parser and plugins,
  * so do not spread `angular.configs.templateRecommended` alongside it.
+ *
+ * @returns {import('typescript-eslint').ConfigArray}
  */
 const templateRecommended = (plugin) => [
     ...angular.configs.templateRecommended,

package/eslint/configs/template-rules.mjs

@@ -1,7 +1,11 @@
 import templateBase from './template-base.mjs';
 
-// Only the rules written by this library. `templateRecommended` includes it, alongside
-// the house style; use this layer directly to opt out of the latter.
+/**
+ * Only the rules written by this library. `templateRecommended` includes it, alongside
+ * the house style; use this layer directly to opt out of the latter.
+ *
+ * @returns {import('typescript-eslint').ConfigArray}
+ */
 const templateRules = (plugin) => [
     templateBase(plugin),
     {

package/eslint/configs/ts-recommended.mjs

@@ -14,6 +14,8 @@ import tsRules from './ts-rules.mjs';
  * Meant for the `extends` of a `**\/*.ts` block. It brings its own parser and plugins,
  * so do not spread `angular.configs.tsRecommended` alongside it — declaring the same
  * plugin twice from two different copies makes ESLint fail outright.
+ *
+ * @returns {import('typescript-eslint').ConfigArray}
  */
 const tsRecommended = (plugin) => [
     eslint.configs.recommended,

package/eslint/configs/ts-rules.mjs

@@ -1,7 +1,11 @@
 import tsBase from './ts-base.mjs';
 
-// Only the rules written by this library. `tsRecommended` includes it, alongside the
-// house style; use this layer directly to opt out of the latter.
+/**
+ * Only the rules written by this library. `tsRecommended` includes it, alongside the
+ * house style; use this layer directly to opt out of the latter.
+ *
+ * @returns {import('typescript-eslint').ConfigArray}
+ */
 const tsRules = (plugin) => [
     tsBase(plugin),
     {

package/eslint/index.mjs

@@ -1,9 +1,17 @@
+import specTsRecommended from './configs/spec-ts-recommended.mjs';
 import templateRecommended from './configs/template-recommended.mjs';
 import templateRules from './configs/template-rules.mjs';
 import tsRecommended from './configs/ts-recommended.mjs';
 import tsRules from './configs/ts-rules.mjs';
 import rules from './rules/index.mjs';
 
+// Only needed by the projects linting Vitest specs: the other configs can be used without it.
+const vitest = await import('@vitest/eslint-plugin').then(
+    (module) => module.default,
+    () => null,
+);
+const specTsRecommendedConfig = vitest ? specTsRecommended(vitest) : null;
+
 const plugin = {
     meta: { name: '@dsivd/prestations-ng' },
     rules,
@@ -16,6 +24,15 @@ const configs = {
     // Only this library's own rules, for a project that supplies its own style.
     tsRules: tsRules(plugin),
     templateRules: templateRules(plugin),
+    // The preset of the Vitest specs (needs @vitest/eslint-plugin)
+    get specTsRecommended() {
+        if (!specTsRecommendedConfig) {
+            throw new Error(
+                'prestationsNg.configs.specTsRecommended needs @vitest/eslint-plugin: npm install --save-dev @vitest/eslint-plugin@1',
+            );
+        }
+        return specTsRecommendedConfig;
+    },
 };
 
 export { configs, plugin, rules };

package/eslint/rules/no-direct-signal-mutation.mjs

@@ -241,7 +241,7 @@ function boundNameSignalKind(identifier, scopeContext, seen) {
     scopeContext.sourceCode.getScope(identifier),
     identifier.name,
   );
-  if (!variable || variable.defs.length !== 1 || seen.has(variable)) {
+  if (variable?.defs.length !== 1 || seen.has(variable)) {
     return undefined;
   }
   seen.add(variable);

package/eslint/signal-names.mjs

@@ -153,6 +153,67 @@ const reExportedModulesOf = (sourceFile) =>
     .filter((statement) => ts.isExportDeclaration(statement) && statement.moduleSpecifier)
     .map((statement) => statement.moduleSpecifier.text);
 
+const classDeclarationsOf = (sourceFile, className) =>
+  className
+    ? [findClass(sourceFile, className)].filter(Boolean)
+    : sourceFile.statements.filter(ts.isClassDeclaration);
+
+const isBarrelMiss = (className, classDeclarations) =>
+  Boolean(className) && classDeclarations.length === 0;
+
+const collectFromReExports = (sourceFile, path, className, kinds, visited) => {
+  for (const specifier of reExportedModulesOf(sourceFile)) {
+    const target = resolveModule(specifier, path);
+    if (target) {
+      collect(target, className, kinds, visited);
+    }
+  }
+};
+
+const addMemberKindIfEligible = (member, kinds) => {
+  if (!member.name || !ts.isIdentifier(member.name)) {
+    return;
+  }
+  const kind = kindOfMember(member);
+  // A subclass overriding a member wins: it is collected first.
+  if (kind && !kinds.has(member.name.text)) {
+    kinds.set(member.name.text, kind);
+  }
+};
+
+const collectMemberKinds = (classDeclaration, kinds) => {
+  for (const member of classDeclaration.members) {
+    addMemberKindIfEligible(member, kinds);
+  }
+};
+
+const baseTargetOf = (sourceFile, path, classDeclaration) => {
+  const baseName = extendedClassNameOf(classDeclaration);
+  if (!baseName) {
+    return undefined;
+  }
+
+  // Declaration bundles are flattened: the base class often sits in the same file.
+  if (findClass(sourceFile, baseName)) {
+    return { path, className: baseName };
+  }
+
+  const imported = importOf(sourceFile, baseName);
+  if (!imported) {
+    return undefined;
+  }
+
+  const target = resolveModule(imported.specifier, path);
+  return target ? { path: target, className: imported.exportedName } : undefined;
+};
+
+const collectBase = (sourceFile, path, classDeclaration, kinds, visited) => {
+  const target = baseTargetOf(sourceFile, path, classDeclaration);
+  if (target) {
+    collect(target.path, target.className, kinds, visited);
+  }
+};
+
 const collect = (path, className, kinds, visited) => {
   const key = `${path}::${className ?? "*"}`;
   if (visited.has(key)) {
@@ -165,47 +226,17 @@ const collect = (path, className, kinds, visited) => {
     return;
   }
 
-  const classDeclarations = className
-    ? [findClass(sourceFile, className)].filter(Boolean)
-    : sourceFile.statements.filter(ts.isClassDeclaration);
+  const classDeclarations = classDeclarationsOf(sourceFile, className);
 
   // A barrel: the class is only re-exported from here.
-  if (className && classDeclarations.length === 0) {
-    for (const specifier of reExportedModulesOf(sourceFile)) {
-      const target = resolveModule(specifier, path);
-      if (target) {
-        collect(target, className, kinds, visited);
-      }
-    }
+  if (isBarrelMiss(className, classDeclarations)) {
+    collectFromReExports(sourceFile, path, className, kinds, visited);
     return;
   }
 
   for (const classDeclaration of classDeclarations) {
-    for (const member of classDeclaration.members) {
-      if (!member.name || !ts.isIdentifier(member.name)) {
-        continue;
-      }
-      const kind = kindOfMember(member);
-      // A subclass overriding a member wins: it is collected first.
-      if (kind && !kinds.has(member.name.text)) {
-        kinds.set(member.name.text, kind);
-      }
-    }
-
-    const baseName = extendedClassNameOf(classDeclaration);
-    if (!baseName) {
-      continue;
-    }
-    // Declaration bundles are flattened: the base class often sits in the same file.
-    if (findClass(sourceFile, baseName)) {
-      collect(path, baseName, kinds, visited);
-      continue;
-    }
-    const imported = importOf(sourceFile, baseName);
-    const target = imported && resolveModule(imported.specifier, path);
-    if (target) {
-      collect(target, imported.exportedName, kinds, visited);
-    }
+    collectMemberKinds(classDeclaration, kinds);
+    collectBase(sourceFile, path, classDeclaration, kinds, visited);
   }
 };