@dsivd/prestations-ng 19.2.0-beta.16 → 19.2.0-beta.18

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/CHANGELOG.md CHANGED
@@ -14,7 +14,8 @@
14
14
  - New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
15
15
  `**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
16
16
  the `HttpTestingController` and of the helpers of the specs. It needs `@vitest/eslint-plugin` in the
17
- devDependencies of your project, only when you use it. See
17
+ devDependencies of your project, only when you use it: 1.6.27 with the TypeScript 5.9 of Angular 21, later
18
+ versions need TypeScript 6. See
18
19
  [UPGRADING_V19.md](UPGRADING_V19.md#migrate-to-eslint-flat-configuration).
19
20
  - [foehn-bo-multi-upload.component.ts](projects/prestations-ng/src/foehn-upload/foehn-bo-multi-upload/foehn-bo-multi-upload.component.ts)
20
21
  - New `localUpload` input. When set to `true`, selected files are kept purely local
@@ -76,6 +77,10 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
76
77
  and therefore the `helpModal` of the `foehn-input-*` components. Other values, such as `modal-xs`, are not
77
78
  Bootstrap classes, had no effect and no longer compile: replace them with `modal-md` to keep the same size
78
79
  (removing them in a `HelpModal` would fall back to `modal-lg`).
80
+ - [foehn-table.component.ts](projects/prestations-ng/src/foehn-table/foehn-table.component.ts)
81
+ - 🚨 `columnsConfiguration` is now an `input()` instead of a `model()`: the table never changes it. The
82
+ two-way binding `[(columnsConfiguration)]` and the `columnsConfigurationChange` output no longer exist, and
83
+ `columnsConfiguration.set()` no longer compiles: bind it with `[columnsConfiguration]`.
79
84
  - 🚀 **prestations-ng is now zoneless**: its components no longer need zone.js to be refreshed. They keep
80
85
  working in an application using zone.js, and your application can now drop zone.js, see
81
86
  [UPGRADING_V19.md](UPGRADING_V19.md#zoneless-optional-but-recommended).
@@ -88,9 +93,9 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
88
93
  the locale of `foehn-date-picker`, the default country and the sanitized model of `foehn-input-address`
89
94
  - `providePrestationsNgCore()` now provides `provideBrowserGlobalErrorListeners()`: without zone.js, the
90
95
  errors thrown in a timer or a promise still reach your `ErrorHandler`
91
- - 🚨 **The inputs and outputs of the components are unchanged**, but the following public fields are now
92
- signals. If your code reads them (e.g. through `viewChild()` or in your tests), call them (`isVisible()`
93
- instead of `isVisible`) and write them with `.set()`. Those marked _read-only_ are `computed()` signals.
96
+ - 🚨 **The inputs and outputs of the components are unchanged** (except `columnsConfiguration` of `foehn-table`,
97
+ see above), but the following public fields are now signals. If your code reads them (e.g. through
98
+ `viewChild()` or in your tests), call them (`isVisible()` instead of `isVisible`) and write them with `.set()`. Those marked _read-only_ are `computed()` signals.
94
99
  - `foehn-agenda`: `srAnnouncements`
95
100
  - `foehn-agenda-timeslot-panel`: `selectedTimeSlot`, `timeInputValue`, `isClosed`, `timeSlots`
96
101
  (_read-only_), `timeslotRemaining` (_read-only_), `canClose` (_read-only_)
@@ -115,7 +120,7 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
115
120
  - `foehn-input-nav13`: `part2`, `part3`, `part4`
116
121
  - `foehn-input-textarea`: `isCharCountExceeded`, `charCountLeft`, `charCountLabel`, `ariaLiveStatus`
117
122
  - `foehn-list` and `foehn-table`: `currentPage`, `filteredList`
118
- - `foehn-list-summary`: `listCopyForTable`, `tableConfiguration` (_read-only_)
123
+ - `foehn-list-summary`: `listCopyForTable` (_read-only_), `tableConfiguration` (_read-only_)
119
124
  - `foehn-notfound`: `seconds`
120
125
  - `foehn-page`: `pageTitle`
121
126
  - `foehn-page-counter`: `isStable` (was an `Observable<boolean>`)
@@ -221,6 +226,9 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
221
226
  new one at each read made the `async` pipe of a template subscribe again at each refresh: on a resumed application
222
227
  whose form is loaded before the session, `isReady` went back to `null` and hid the content until the session
223
228
  arrived.
229
+ - `foehn-list-summary` with `showAsTable`: the table displays the list given by the page when the page replaces it
230
+ (e.g. with the form returned by the backend). Since 19.0.0, it only followed the removals and the sorts made in
231
+ the component.
224
232
  - `ng add @dsivd/prestations-ng` works again on the Angular workspaces created since Angular 14: it failed because
225
233
  `angular.json` no longer has a `defaultProject` (the dependencies are now added to every application), then
226
234
  because of the comments of `tsconfig.json` (now kept, like its formatting).
package/CONTRIBUTING.md CHANGED
@@ -221,6 +221,34 @@ export NODE_OPTIONS=--max_old_space_size=4096
221
221
 
222
222
  Use at your own risks.
223
223
 
224
+ ## Writing signal-first code
225
+
226
+ The library is zoneless: Angular refreshes a component when a signal read by its template changes, or when the
227
+ component is notified (see "Zoneless application" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md) and
228
+ [ANGULAR_SIGNALS.md](ANGULAR_SIGNALS.md)). Write the code as it would be written today with signals, not around a
229
+ mechanism inherited from zone.js:
230
+
231
+ - State read by a template: a `signal()`. State derived from other signals (inputs, model, view queries): a
232
+ `computed()`, or a `linkedSignal()` when it can also be changed locally. Don't keep a signal in sync from
233
+ `ngOnChanges()`, `onModelChange()`, an `effect()` or a `setTimeout()` when it can be derived.
234
+ - React to a signal input with `computed()` or `linkedSignal()`, not with `ngOnChanges()`.
235
+ - Never mutate a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new array or
236
+ object. No copy is then needed "so that the change detection sees a new reference".
237
+ - Asynchronous work: set a signal in the callback, or convert the `Observable` with `toSignal()` where it is
238
+ displayed. The services keep returning `Observable`s.
239
+ - `markForCheck()` only for a state that can't be a signal (e.g. the `form` of `AbstractPageComponent`, written by
240
+ the projects).
241
+ - Act on the rendered DOM (focus, scroll, measure) with `afterNextRender(..., { injector })`, never with
242
+ `setTimeout()` or `NgZone`.
243
+ - `effect()` as a last resort, with `untracked()` for what isn't a trigger. Never use it to copy a signal into another
244
+ one.
245
+ - Track the short asynchronous work the tests must wait for (e.g. a debounce) with `PendingTasks`.
246
+ - Before fixing existing code, read the history of the mechanism you touch (`git log -S`, `git blame`): many
247
+ `setTimeout()`, copies, `ngOnChanges()` and `NgZone` are workarounds from the zone.js era whose reason is gone. If
248
+ the code wouldn't be written this way today, rewrite it rather than patching around it.
249
+ - A public field of a component that becomes a signal changes how the projects read it: list it in the CHANGELOG
250
+ (_read-only_ for a `computed()`), with 🚨 when an input or an output changes.
251
+
224
252
  ## Unit testing
225
253
 
226
254
  The unit tests run with [Vitest](https://vitest.dev/) through the `@angular/build:unit-test` builder of the
@@ -253,8 +281,10 @@ Neither the library nor the Dev Tool uses zone.js: the tests are **zoneless** to
253
281
  The spies are restored before each test.
254
282
  - `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` require zone.js: use `async` tests with
255
283
  `await fixture.whenStable()`, or `vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)`.
256
- - `fixture.whenStable()` waits for the change detection and the Angular pending tasks (HTTP requests...), not
257
- for the timers.
284
+ - `fixture.whenStable()` waits for the change detection and the Angular pending tasks (e.g. the debounced
285
+ `userInput` of the inputs), not for the timers, nor for the HTTP requests of a spec: `provideHttpClientTesting()`
286
+ keeps them pending until the test answers them with `HttpTestingController`. Answer them first, then
287
+ `await fixture.whenStable()`.
258
288
  - Without zone.js, `fixture.detectChanges()` only refreshes the views that have been notified. A test (or a test
259
289
  host component) changing the state of a component must use signals, as the components do.
260
290
 
package/GOOD_PRACTICES.md CHANGED
@@ -418,8 +418,8 @@ export class PageOneComponent
418
418
  ### Displaying an asynchronous state
419
419
 
420
420
  > ⚠️ A field modified elsewhere (in a `subscribe()`, a `setTimeout()`, a `Promise`, a
421
- > callback, ...) is no longer displayed until something else refreshes the component. Hold it in
422
- > a **signal**.
421
+ > callback, an `effect()`, ...) is no longer displayed until something else refreshes the component.
422
+ > Hold it in a **signal**.
423
423
 
424
424
  What **not** to do:
425
425
 
@@ -454,9 +454,14 @@ ngOnInit(): void {
454
454
  > 💡 For an observable displayed as is, `toSignal(this.myService.load())` or the `async` pipe do
455
455
  > the job for you.
456
456
 
457
- In your pages (`AbstractPageComponent`), prestations-ng refreshes the page when it loads `form`
458
- and `reference`. If you modify the form yourself in an asynchronous callback, call
459
- `markForCheck()` afterwards:
457
+ Do the same for a field read by the template that only a method called by a listener of the template
458
+ modifies: the listener notifies Angular, but the same method can later be called from a `subscribe()`
459
+ or an `effect()`, and the field would no longer be displayed. A signal notifies Angular whoever
460
+ modifies it.
461
+
462
+ In your pages (`AbstractPageComponent`), `form` can't be a signal. prestations-ng refreshes the page
463
+ when it loads `form` and `reference`, but whenever your code modifies the form, call `markForCheck()`
464
+ after the modifications, whoever calls the method (a listener, a callback, an `effect()`, ...):
460
465
 
461
466
  ```ts
462
467
  private readonly changeDetectorRef = inject(ChangeDetectorRef);
@@ -465,13 +470,19 @@ ngOnInit(): void {
465
470
  super.ngOnInit();
466
471
  this.sessionInfoWithApplicationService.prefillForm((info) => {
467
472
  if (this.form) {
468
- this.form.email = info?.email ?? null;
473
+ this.form.firstName = info?.firstName ?? null;
474
+ this.form.lastName = info?.lastName ?? null;
469
475
  this.changeDetectorRef.markForCheck();
470
476
  }
471
477
  });
472
478
  }
473
479
  ```
474
480
 
481
+ - Once after the last modification is enough: Angular refreshes the page later, with all the
482
+ modifications of the method. After an `await`, or in another callback, call it again.
483
+ - A signal modified next to the form doesn't replace it: `set()` notifies Angular only when the value
484
+ changes (e.g. an amount recalculated identical), and only refreshes the views reading the signal.
485
+
475
486
  If a service fills the form for the page, the page must still be notified: let the service return an
476
487
  `Observable` (or take a callback), and call `markForCheck()` in the page.
477
488
 
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
 
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`
@@ -1065,9 +1065,12 @@ npm install --save-dev eslint-config-prettier@10
1065
1065
  npm install --save-dev eslint-plugin-import-x@4
1066
1066
  npm install --save-dev prettier
1067
1067
  # only if your project has Vitest specs (see "Migrate to vitest")
1068
- npm install --save-dev @vitest/eslint-plugin@1
1068
+ npm install --save-dev --save-exact @vitest/eslint-plugin@1.6.27
1069
1069
  ```
1070
1070
 
1071
+ `@vitest/eslint-plugin` 1.6.28 and later need TypeScript 6: with the TypeScript 5.9 of Angular 21, `npm install` fails
1072
+ with `ERESOLVE`. Keep 1.6.27 until your project moves to TypeScript 6.
1073
+
1071
1074
  In your `front` folder, add a `.prettierrc` file with the following content:
1072
1075
 
1073
1076
  ```json
@@ -1621,9 +1624,10 @@ Without zone.js, Angular refreshes a component only when it is notified that som
1621
1624
  - a signal read by its template has changed (`signal()`, `computed()`, `input()`, `model()`, `toSignal()`...)
1622
1625
  - `ChangeDetectorRef.markForCheck()` has been called, which is what the `async` pipe does when an observable emits
1623
1626
 
1624
- A field modified elsewhere (in a `subscribe()`, a `setTimeout()`, a `Promise`, a callback...) is not displayed
1625
- anymore until something else refreshes the component. Hold it in a signal (see
1626
- [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md)):
1627
+ A field modified elsewhere (in a `subscribe()`, a `setTimeout()`, a `Promise`, a callback, an `effect()`...) is not
1628
+ displayed anymore until something else refreshes the component. Hold it in a signal (see
1629
+ [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md)), as well as the fields read by the template that
1630
+ only a method called by a listener modifies: this method can later be called from elsewhere.
1627
1631
 
1628
1632
  ```diff
1629
1633
  - isLoading = true;
@@ -1644,10 +1648,11 @@ anymore until something else refreshes the component. Hold it in a signal (see
1644
1648
 
1645
1649
  Pay attention to:
1646
1650
 
1647
- - your pages (`AbstractPageComponent` and its subclasses): prestations-ng refreshes them when it sets `form` and
1648
- `reference`. But if you modify the form yourself in an asynchronous callback, e.g. the one given to
1649
- `SessionInfoWithApplicationService.prefillForm()` or a `subscribe()` of your own service, call
1650
- `markForCheck()` afterwards:
1651
+ - your pages (`AbstractPageComponent` and its subclasses): `form` can't be a signal. prestations-ng refreshes them
1652
+ when it sets `form` and `reference`, but whenever your code modifies the form, call `markForCheck()` once after the
1653
+ modifications, whoever calls the method: a listener, an asynchronous callback (e.g. the one given to
1654
+ `SessionInfoWithApplicationService.prefillForm()` or a `subscribe()` of your own service), an `effect()`... A
1655
+ signal modified next to the form doesn't replace it: `set()` notifies Angular only when the value changes.
1651
1656
 
1652
1657
  ```ts
1653
1658
  private readonly changeDetectorRef = inject(ChangeDetectorRef);
@@ -1656,7 +1661,8 @@ Pay attention to:
1656
1661
  super.ngOnInit();
1657
1662
  this.sessionInfoWithApplicationService.prefillForm((info) => {
1658
1663
  if (this.form) {
1659
- this.form.email = info?.email ?? null;
1664
+ this.form.firstName = info?.firstName ?? null;
1665
+ this.form.lastName = info?.lastName ?? null;
1660
1666
  this.changeDetectorRef.markForCheck();
1661
1667
  }
1662
1668
  });