@dsivd/prestations-ng 19.2.0-beta.24 → 19.2.0-beta.26

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
@@ -25,9 +25,9 @@
25
25
  - `FoehnInputComponent.patchNgModel(path, value)` (since 19.2.0-beta.22): writes a value at a typed path of the
26
26
  model, in a new model given to `updateNgModel()`, e.g.
27
27
  `[model]="model()?.lastName" (modelChange)="patchNgModel(['lastName'], $event)"` in a component editing an object
28
- as is, or `patchNgModel([index], item)` in a list. The new protected `emptyModel()` gives the model it starts from
29
- when the page gives none (none by default: `patchNgModel()` then throws). See "Editing an object field by field" in
30
- [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
28
+ as is, or `(modelChange)="patchNgModel([i], $event)"` on the items of a list. The new protected `emptyModel()`
29
+ gives the model it starts from when the page gives none (none by default: `patchNgModel()` then throws). See
30
+ "Editing an object field by field" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
31
31
  - `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
32
32
  classes and their templates (see the 🚨 entries below and
33
33
  [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
@@ -192,6 +192,10 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
192
192
  only takes strings, numbers, booleans, `null`, `undefined`, `any` and `RegExp`: a signal not called
193
193
  (`` `api/${this.reference}` ``) or an object turned into text by its `toString()` is reported. See
194
194
  [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#the-typescript-counterpart).
195
+ - 🚨 ESLint: `configs.tsRecommended` enables `@typescript-eslint/no-useless-constructor` (since 19.2.0-beta.26). A
196
+ constructor only passing its parameters to `super()`, typically the `constructor() { super(); }` left once the
197
+ services are injected with `inject()`, is reported: remove it. See
198
+ [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#a-constructor-only-calling-super) for a parent with a `protected` constructor.
195
199
  - 🚨 `AbstractPageComponent`: `form` is now a signal (`WritableSignal<T | null | undefined>`). Read it with `form()`,
196
200
  never modify its value in place: write it with the new `patchForm(path, value)`
197
201
  (`[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`), `form.set()` or `form.update()`. A
@@ -236,9 +240,9 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
236
240
  [UPGRADING_V19.md](UPGRADING_V19.md#your-components-write-a-new-model). A component modifying its model in place
237
241
  and giving it back no longer notifies its page. The list of vehicles of [GOOD_PRACTICES.md](GOOD_PRACTICES.md) now
238
242
  shows a complete item, its fields in linked signals, and a list which reads its `model()` and writes a new array.
239
- - `FoehnInputComponent.updateNgModel()` is typed `T | null | undefined`, as the `modelChange` of a `foehn-*`
240
- component: a component wrapping a single `foehn-*` component binds it with `(modelChange)="updateNgModel($event)"`,
241
- which `strictTemplates` rejected (TS2345) when the wrapped component is typed. Nothing changes at runtime:
243
+ - `FoehnInputComponent.updateNgModel()` is typed `T | null | undefined` (since 19.2.0-beta.24), as the `modelChange`
244
+ of a `foehn-*` component: a component wrapping a single `foehn-*` component binds it with
245
+ `(modelChange)="updateNgModel($event)"`, which `strictTemplates` rejected (TS2345). Nothing changes at runtime:
242
246
  `undefined` is written as is.
243
247
  - 🚨 The `onModelChange()` methods which were not the hook of `FoehnInputComponent` are removed or renamed (they are
244
248
  not called by the model anymore):
package/ESLINT_PLUGIN.md CHANGED
@@ -62,9 +62,11 @@ here they bring:
62
62
  stylistic, `angular-eslint` recommended, and for templates its accessibility set;
63
63
  - the house style — naming and selector conventions, import ordering
64
64
  (`simple-import-sort`, `import-x`), rxjs conventions, the signal rules of
65
- `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`), and
65
+ `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`),
66
66
  `@typescript-eslint/restrict-template-expressions` (see
67
- [The TypeScript counterpart](#the-typescript-counterpart)).
67
+ [The TypeScript counterpart](#the-typescript-counterpart)), and
68
+ `@typescript-eslint/no-useless-constructor` (see
69
+ [A constructor only calling `super()`](#a-constructor-only-calling-super)).
68
70
 
69
71
  Use `tsRules` / `templateRules` instead when a project supplies its own style and only wants
70
72
  the rules of this library. They register the plugin and nothing else, so you keep control of
@@ -428,3 +430,18 @@ called is reported, as is an object turned into text by its `toString()`. With
428
430
  ```ts
429
431
  '@typescript-eslint/restrict-template-expressions': 'error',
430
432
  ```
433
+
434
+ ## A constructor only calling `super()`
435
+
436
+ `configs.tsRecommended` enables `@typescript-eslint/no-useless-constructor`: a constructor
437
+ which only passes its parameters to `super()` is reported, typically the
438
+ `constructor() { super(); }` left once the services are injected with `inject()`. Remove it:
439
+ the class inherits the constructor of its parent. A `protected` or `private` constructor is
440
+ not reported, nor one giving other arguments to its parent (`super(Type.SUBSIDY)`).
441
+
442
+ When the removal gives `Cannot assign a 'protected' constructor type to a 'public'
443
+ constructor type` (TS2322 on the `component` of a route, TS2345 on
444
+ `TestBed.createComponent()`), the parent declares a `protected constructor()`, which the
445
+ class now inherits. Remove that one too when the parent is `abstract`: it already can't be
446
+ instantiated. Otherwise keep the constructor of the class, with an `eslint-disable-next-line`
447
+ saying why.
package/GOOD_PRACTICES.md CHANGED
@@ -1003,14 +1003,15 @@ export class OwnerAddress {
1003
1003
 
1004
1004
  ```ts
1005
1005
  export class OwnerInputComponent extends FoehnInputComponent<Owner> {
1006
- // The owner patchNgModel() starts from as long as the page gives none
1007
- protected override emptyModel(): Owner {
1008
- return new Owner();
1009
- }
1010
-
1011
1006
  handleUserInput(): void {
1012
1007
  this.handleChange(this.model() ?? null);
1013
1008
  }
1009
+
1010
+ // The owner patchNgModel() starts from as long as the page gives none (protected: after the
1011
+ // public members, as @typescript-eslint/member-ordering requires)
1012
+ protected override emptyModel(): Owner {
1013
+ return new Owner();
1014
+ }
1014
1015
  }
1015
1016
  ```
1016
1017
 
@@ -1042,12 +1043,57 @@ export class OwnerInputComponent extends FoehnInputComponent<Owner> {
1042
1043
  component whose model is always given doesn't override it. Without one, `patchNgModel()`
1043
1044
  throws, as it does when an object of the path is `null` or `undefined`: hence the class `Owner`
1044
1045
  creating its `address`.
1045
- - Several fields at once: `updateNgModel()` with a new object, e.g.
1046
- `{ ...this.model(), lastName, firstName }`. A value derived from the object: a `computed()`
1047
- reading `model()`.
1046
+ - Several fields at once: `updateNgModel()` with a new object of the class, e.g.
1047
+ `Object.assign(new Owner(), this.model(), { lastName, firstName })`. A spread
1048
+ (`{ ...this.model(), lastName }`) gives a plain object, whereas `patchNgModel()` keeps the class
1049
+ of the objects it copies.
1050
+ - A rule applied at each write (e.g. fields emptied according to another one, a total saved with
1051
+ the object): override `updateNgModel()`, and give `super.updateNgModel()` the corrected object,
1052
+ e.g. with `ObjectPathHelper.patch()`. `patchNgModel()` goes through it, as every other write
1053
+ (see `foehn-input-number`). A value only displayed is rather a `computed()` reading `model()`.
1048
1054
  - No linked signal and no `getValidValue()`: the component keeps no state of its own, each change
1049
- goes at once to the model, which the template reads again. An object whose fields are emptied
1050
- stays an object (point 8 doesn't apply).
1055
+ goes at once to the model, which the template reads again, and the fields it doesn't display
1056
+ (an id, a version) are kept, as no object is rebuilt by hand. An object whose fields are emptied
1057
+ stays an object, its fields `null`.
1058
+ - When the backend expects `null` for an emptied object (point 8, e.g. an optional object
1059
+ validated by `@Valid`, whose required fields would otherwise be reported), apply it at each
1060
+ write, in the override of `updateNgModel()`:
1061
+
1062
+ ```ts
1063
+ override updateNgModel(value: Owner | null): void {
1064
+ if (ObjectHelper.hasAnyValue(value)) {
1065
+ super.updateNgModel(value);
1066
+ } else if (this.model_ !== undefined) {
1067
+ super.updateNgModel(null);
1068
+ }
1069
+ }
1070
+ ```
1071
+
1072
+ As in point 8, `null` only once the model is known: a field correcting the model given by
1073
+ the page (e.g. `''` replaced by `null`) also emits `modelChange`, and an object without any
1074
+ value given by the page must not be replaced by `null` without an input of the user.
1075
+
1076
+ ### Wrapping a single component
1077
+
1078
+ A component which wraps a single `foehn-*` component, to which it gives its whole model (e.g. a
1079
+ `foehn-input-address` or a `foehn-checkbox` with the label, the help or the elements of your
1080
+ prestation), passes its model through, without a copy:
1081
+
1082
+ ```html
1083
+ <!-- ... with its name, its label, its elements... -->
1084
+ <foehn-input-address
1085
+ [model]="model()"
1086
+ (modelChange)="updateNgModel($event)"
1087
+ (userInput)="handleChange($event)"
1088
+ />
1089
+ ```
1090
+
1091
+ - No copy of the model, in a field or a `linkedSignal()`: the wrapped component already writes a
1092
+ new value.
1093
+ - No `[(model)]="model"`: the two-way binding writes the model with `set()`, which bypasses
1094
+ `updateNgModel()` (`model_`, the model of a disabled component left alone).
1095
+ - A rule applied at each write: override `updateNgModel()`, as for an object edited field by
1096
+ field.
1051
1097
 
1052
1098
  ### Displaying the global validation of the component
1053
1099
 
@@ -1353,7 +1399,7 @@ must also send the event up.
1353
1399
  <app-vehicule-item
1354
1400
  [name]="name() + '[' + i + ']'"
1355
1401
  [model]="vehicule"
1356
- (modelChange)="updateVehiculesList($event, i)"
1402
+ (modelChange)="patchNgModel([i], $event)"
1357
1403
  (userInput)="handleUserInput()"
1358
1404
  (removedVehicule)="handleRemovedVehicule(i)"
1359
1405
  />
@@ -1369,7 +1415,9 @@ must also send the event up.
1369
1415
  > `[name]="name + '[' + i + ']'"`).
1370
1416
  >
1371
1417
  > 💡 The variable of a `@for` loop can't be modified: the item is passed with `[model]`, and
1372
- > the item of the list is replaced in `updateVehiculesList()` (called by `(modelChange)`).
1418
+ > its `(modelChange)` replaces the item of the list with `patchNgModel([i], $event)`, in a new
1419
+ > list. With `strictTemplates`, TypeScript checks the path `[i]` and the vehicle `$event`. A method
1420
+ > of the list is only needed when it adds something to the replacement of the item.
1373
1421
 
1374
1422
  `vehicules-list.component.ts` in turn sends the event (1) up to the parent (`AbstractPageComponent`)
1375
1423
  and removes the item from the list (2). This is also where you can handle the addition of an
@@ -1394,11 +1442,6 @@ item (3). Each change writes a new list in the model (4).
1394
1442
  export class VehiculesListComponent extends FoehnInputComponent<Vehicule[]> {
1395
1443
  readonly removedVehicule = output<void>(); // (1) event to send up to the parent
1396
1444
 
1397
- // Called by the (modelChange) of an item: the item is replaced in a new list
1398
- updateVehiculesList(vehicule: Vehicule, index: number): void {
1399
- this.patchNgModel([index], vehicule);
1400
- }
1401
-
1402
1445
  handleUserInput(): void {
1403
1446
  const validValue = this.getValidValue(this.model() ?? []);
1404
1447
  if (typeof validValue !== 'undefined') {
package/UPGRADING_V19.md CHANGED
@@ -1479,8 +1479,11 @@ the component works on another one (e.g. an object it created or replaced itself
1479
1479
  Search your components extending `FoehnInputComponent` for a `getValidValue()` returning a field (`return this.items;`,
1480
1480
  `return this.item;`) and for the writes in place of their model, and give `updateNgModel()` a new object or array:
1481
1481
 
1482
- - a list reads its `model()` directly, replaces an item with `patchNgModel([index], item)`, and adds or removes one
1483
- with a new array (`[...list, item]`, `filter()`);
1482
+ - a list reads its `model()` directly, replaces an item from its template with
1483
+ `(modelChange)="patchNgModel([i], $event)"`, and adds or removes one with a new array (`[...list, item]`,
1484
+ `filter()`);
1485
+ - a component wrapping a single `foehn-*` component, to which it gives its whole model, binds it with
1486
+ `[model]="model()" (modelChange)="updateNgModel($event)"`, without a copy;
1484
1487
  - a component editing an object as is reads its `model()` directly, and writes each field with
1485
1488
  `patchNgModel(['address', 'street'], $event)` (since 19.2.0-beta.22), which keeps the fields it doesn't display (an
1486
1489
  id, a tracking index). Override `emptyModel()` when the page can give no object;
@@ -92,6 +92,11 @@ const tsRecommended = (plugin) => [
92
92
  // off here — @typescript-eslint/no-shadow handles it correctly for TS
93
93
  'no-shadow': 'off',
94
94
  '@typescript-eslint/no-shadow': ['error', { hoist: 'all' }],
95
+ // a constructor only passing its parameters to super(), e.g. the
96
+ // `constructor() { super(); }` left once the services are injected with
97
+ // inject(); off here — the core rule ignores the parameter properties
98
+ 'no-useless-constructor': 'off',
99
+ '@typescript-eslint/no-useless-constructor': 'error',
95
100
  '@typescript-eslint/no-unused-vars': [
96
101
  'error',
97
102
  {
@@ -975,7 +975,8 @@ class FoehnInputComponent {
975
975
  * Writes a value at a path of the model, in a new model: the objects and arrays along the path are copied, the
976
976
  * others are kept as they are (`ObjectPathHelper`), and the result goes through `updateNgModel()`. Bind a field of
977
977
  * an object edited as is with `[model]="model()?.firstName" (modelChange)="patchNgModel(['firstName'], $event)"`,
978
- * or replace an item of a list with `patchNgModel([index], item)`. The same value changes nothing.
978
+ * or replace an item of a list with `[model]="item" (modelChange)="patchNgModel([$index], $event)"`. The same
979
+ * value changes nothing.
979
980
  *
980
981
  * @param path the keys and indexes leading to the value, e.g. `['address', 'street']` or `[index]`
981
982
  * @param value the new value (`null` and `undefined` included: the model of the `foehn-*` components can be)