@dsivd/prestations-ng 19.2.0-beta.17 → 19.2.0-beta.19

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
@@ -202,6 +203,21 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
202
203
  - `foehn-input-address`: the deferred clean-up of the model (hidden address lines and post office box) applies
203
204
  to the latest model, it could restore a previous value (e.g. remove the default country); nothing is
204
205
  updated anymore once the component is destroyed.
206
+ - `FoehnInputComponent`: when the user empties at once every field of a model given by the page, the model is `null`
207
+ again, as in v18, for the components overriding `onModelChange()` without calling `super.onModelChange()`: in
208
+ prestations-ng `foehn-input-date`, `foehn-input-date-time`, `foehn-input-foreign-locality` and
209
+ `foehn-input-foreign-street` (also in the foreign address of `foehn-input-address`), and in your project e.g. a
210
+ list whose last item is removed. Since 19.0.0, the model kept its previous value, which was then saved. The model
211
+ of the page is now known (`model_`) once it has a value to display, before `onModelChange()`, which can still
212
+ change it. Nothing to change in your components, except one whose model can hold a value only in a part it doesn't
213
+ display (e.g. an id) and which updates its model without any input of the user: override the new protected method
214
+ `hasValueToDisplay()`, as `foehn-input-address` does for the country of an address only Swiss.
215
+ - `foehn-input-date-time`: emptying its only filled field empties the model, it kept its value also in v18.
216
+ - 🚨 `ObjectHelper.hasAnyValue()` and `ObjectHelper.isEmpty()`: a number (`0` included), a boolean (`false`
217
+ included) and a date are values. `true`, `5` or a date were empty, as well as `0`, `false` or a date in an object
218
+ or an array (e.g. `{ checked: false }`, `[0, 0]`). Only `null`, `undefined`, `''` and the arrays and objects
219
+ holding none but them are empty. Check your calls on such values, e.g. in the `getValidValue()` of your
220
+ components: a field holding `true` no longer counts as empty.
205
221
  - `foehn-multi-upload` and `foehn-bo-multi-upload`:
206
222
  - after a failed upload (network, HTTP error), the next files are uploaded: nothing was uploaded anymore,
207
223
  without any message, until the page was reloaded
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
 
@@ -1202,8 +1213,8 @@ item (3).
1202
1213
  export class VehiculesListComponent extends FoehnInputComponent<Vehicule[]> {
1203
1214
  readonly removedVehicule = output<void>(); // (1) event to send up to the parent
1204
1215
 
1205
- // Signal holding your repeatable items: it is replaced, never modified in place
1206
- readonly vehicules = signal<Vehicule[]>([]);
1216
+ // Signal holding your repeatable items, derived from the model: it is replaced, never modified in place
1217
+ readonly vehicules = linkedSignal(() => this.model() ?? []);
1207
1218
 
1208
1219
  updateVehiculesList(vehicule: Vehicule, index: number): void {
1209
1220
  this.vehicules.update((vehicules) =>
@@ -1221,10 +1232,6 @@ export class VehiculesListComponent extends FoehnInputComponent<Vehicule[]> {
1221
1232
  this.removedVehicule.emit(); // (1) the event is sent up
1222
1233
  }
1223
1234
 
1224
- override onModelChange(value: Vehicule[] | null): void {
1225
- this.vehicules.set(value ?? []);
1226
- }
1227
-
1228
1235
  addVehicule(): void {
1229
1236
  // (3) Handling of the addition of an item
1230
1237
  // ...code
package/UPGRADING_V19.md CHANGED
@@ -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
  });
@@ -506,7 +506,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.25", ngImpo
506
506
  }]
507
507
  }] });
508
508
 
509
- /* eslint-disable @typescript-eslint/no-explicit-any */
510
509
  class ObjectHelper {
511
510
  /**
512
511
  * Angular uses object identity to select option. It's possible for the identities of items to change while the data does not.
@@ -523,29 +522,31 @@ class ObjectHelper {
523
522
  value2 &&
524
523
  typeof value1 === 'object' &&
525
524
  typeof value2 === 'object') {
526
- const matches = (obj, source) => Object.keys(source).length === Object.keys(obj).length &&
527
- Object.keys(source).every((key) => {
528
- if (Object.hasOwn(obj, key)) {
529
- if (obj[key] &&
530
- source[key] &&
531
- typeof obj[key] === 'function' &&
532
- typeof source[key] === 'function') {
533
- if (skipFunctionTypeCompare) {
534
- return true;
535
- }
525
+ const matches = (obj, source) => {
526
+ const objValues = obj;
527
+ const sourceValues = source;
528
+ return (Object.keys(source).length === Object.keys(obj).length &&
529
+ Object.keys(source).every((key) => {
530
+ if (!Object.hasOwn(obj, key)) {
531
+ return false;
532
+ }
533
+ const objValue = objValues[key];
534
+ const sourceValue = sourceValues[key];
535
+ if (typeof objValue === 'function' &&
536
+ typeof sourceValue === 'function') {
536
537
  // Didn't find better to compare two functions
537
- return (obj[key].toString() === source[key].toString());
538
+ return (skipFunctionTypeCompare ||
539
+ objValue.toString() === sourceValue.toString());
538
540
  }
539
- if (obj[key] &&
540
- source[key] &&
541
- typeof obj[key] === 'object' &&
542
- typeof source[key] === 'object') {
543
- return matches(obj[key], source[key]);
541
+ if (objValue &&
542
+ sourceValue &&
543
+ typeof objValue === 'object' &&
544
+ typeof sourceValue === 'object') {
545
+ return matches(objValue, sourceValue);
544
546
  }
545
- return obj[key] === source[key];
546
- }
547
- return false;
548
- });
547
+ return objValue === sourceValue;
548
+ }));
549
+ };
549
550
  return matches(value1, value2);
550
551
  }
551
552
  return value1 === value2;
@@ -553,19 +554,31 @@ class ObjectHelper {
553
554
  static isDifferent(value1, value2, skipFunctionType = true) {
554
555
  return !ObjectHelper.isEqual(value1, value2, skipFunctionType);
555
556
  }
557
+ /**
558
+ * @param value to check
559
+ * @returns whether the value isn't `null`, `undefined` or `''`, and, for an array or an object, whether one of its
560
+ * items or properties holds a value (deeply). A number (`0` included), a boolean (`false` included) and a date are
561
+ * values.
562
+ */
556
563
  static hasAnyValue(value) {
557
- if (!value) {
564
+ if (value === null || value === undefined || value === '') {
558
565
  return false;
559
566
  }
560
- // do not simplify with an inline variable result due to compilation error
561
- const result = Object.keys(value).some((key) => {
562
- if (value[key] && typeof value[key] === 'object') {
563
- return ObjectHelper.hasAnyValue(value[key]);
564
- }
565
- return !!value[key];
566
- });
567
- return result;
567
+ if (value instanceof Date) {
568
+ return true;
569
+ }
570
+ if (Array.isArray(value)) {
571
+ return value.some((item) => ObjectHelper.hasAnyValue(item));
572
+ }
573
+ if (typeof value === 'object') {
574
+ return Object.values(value).some((item) => ObjectHelper.hasAnyValue(item));
575
+ }
576
+ return true;
568
577
  }
578
+ /**
579
+ * @param value to check
580
+ * @returns the contrary of {@link hasAnyValue}
581
+ */
569
582
  static isEmpty(value) {
570
583
  return !ObjectHelper.hasAnyValue(value);
571
584
  }
@@ -580,6 +593,7 @@ class ObjectHelper {
580
593
  * @param obj is the object to copied
581
594
  * @returns obj
582
595
  */
596
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the callers use the copy without typing it
583
597
  static deepCopy(obj) {
584
598
  if (!obj || typeof obj !== 'object') {
585
599
  return obj;
@@ -611,18 +625,20 @@ class ObjectHelper {
611
625
  const doc = new DOMParser().parseFromString(html, 'text/html');
612
626
  return doc.body.textContent || '';
613
627
  }
628
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the type of the property depends on the key
614
629
  static getNestedProperty(obj, key) {
615
- for (const property in obj) {
616
- if (Object.hasOwn(obj, property)) {
630
+ const values = obj;
631
+ for (const property in values) {
632
+ if (Object.hasOwn(values, property)) {
617
633
  // in case it is an object
618
- if (typeof obj[property] === 'object') {
619
- const result = this.getNestedProperty(obj[property], key.split('.').slice(1).join('.'));
634
+ if (typeof values[property] === 'object') {
635
+ const result = this.getNestedProperty(values[property], key.split('.').slice(1).join('.'));
620
636
  if (result !== undefined) {
621
637
  return result;
622
638
  }
623
639
  }
624
640
  else if (property === key) {
625
- return obj[key]; // returns the value
641
+ return values[key]; // returns the value
626
642
  }
627
643
  }
628
644
  }
@@ -788,7 +804,16 @@ class FoehnInputComponent {
788
804
  const value = this.model();
789
805
  // Only a change of the model must call onModelChange(), not a change
790
806
  // of the state it reads or updates (which can be signals).
791
- untracked(() => this.onModelChange(value));
807
+ untracked(() => {
808
+ // The model of the page is known (model_) once it has a value to display: when the user empties every
809
+ // field, the getValidValue() of the components then returns null. A model without any value to display
810
+ // stays unknown, so that it is never replaced by null without any input of the user. Set before
811
+ // onModelChange(), which can change it.
812
+ if (this.hasValueToDisplay(value)) {
813
+ this.model_ = value;
814
+ }
815
+ this.onModelChange(value);
816
+ });
792
817
  }, ...(ngDevMode ? [{ debugName: "modelEffect" }] : /* istanbul ignore next */ []));
793
818
  // ECMAScript private fields: cannot collide with a member of the components extending this class.
794
819
  #pendingTasks = inject(PendingTasks);
@@ -1039,6 +1064,16 @@ class FoehnInputComponent {
1039
1064
  }
1040
1065
  return null;
1041
1066
  }
1067
+ /**
1068
+ * Whether a model given by the page has a value to display, which makes it known (`model_`) before
1069
+ * `onModelChange()`: by default, any value (see `ObjectHelper.hasAnyValue()`). To override when the component
1070
+ * doesn't display a part of its model (e.g. the country of an address only Swiss, or an id).
1071
+ * @param value of the model
1072
+ * @returns whether the model has a value to display
1073
+ */
1074
+ hasValueToDisplay(value) {
1075
+ return ObjectHelper.hasAnyValue(value);
1076
+ }
1042
1077
  isEmpty(data) {
1043
1078
  return data === null || data === undefined || data === '';
1044
1079
  }
@@ -9365,6 +9400,10 @@ class FoehnInputAddressComponent extends FoehnInputComponent {
9365
9400
  }
9366
9401
  return !this.street() || !!this.postOfficeBoxText();
9367
9402
  }
9403
+ hasValueToDisplay(value) {
9404
+ // The country isn't displayed when the address is only Swiss (see isModelEmpty())
9405
+ return ObjectHelper.hasAnyValue(this.isOnlySwiss() && value ? { ...value, country: null } : value);
9406
+ }
9368
9407
  sanitizeAddress(value) {
9369
9408
  if (ObjectHelper.isEmpty(value)) {
9370
9409
  return value;
@@ -11867,7 +11906,7 @@ class FoehnTimeComponent extends FoehnInputStringComponent {
11867
11906
  }
11868
11907
  }
11869
11908
  onModelChange(_value) {
11870
- // The hour and the minute are linked signals of the model (model_ is only set by updateNgModel())
11909
+ // The hour and the minute are linked signals of the model
11871
11910
  }
11872
11911
  resetModel() {
11873
11912
  this.hour.set(null);
@@ -12005,7 +12044,7 @@ class FoehnDateTimeComponent extends FoehnInputComponent {
12005
12044
  this.handleUserInput();
12006
12045
  }
12007
12046
  onModelChange(_value) {
12008
- // The date and the time are linked signals of the model (model_ is only set by updateNgModel())
12047
+ // The date and the time are linked signals of the model
12009
12048
  }
12010
12049
  getValidValue() {
12011
12050
  if (this.isEmpty()) {