@dsivd/prestations-ng 19.2.0-beta.3 → 19.2.0-beta.5

package/UPGRADING_V19.md

@@ -1449,6 +1449,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

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),
     {