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

package/UPGRADING_V19.md

@@ -1064,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:
@@ -1140,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,
 );
@@ -1150,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
@@ -1449,6 +1462,172 @@ 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
@@ -1488,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'
 ],

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);