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

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
@@ -10,6 +10,10 @@
10
10
 
11
11
  ### Added
12
12
 
13
+ - [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
14
+ - New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
15
+ `LenientLocalDate` of prestations-be), to type the date fields of your forms, e.g.
16
+ `birthDate: FoehnDateModel | null = null;`.
13
17
  - [eslint/configs/spec-ts-recommended.mjs](projects/prestations-ng/src/eslint/configs/spec-ts-recommended.mjs)
14
18
  - New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
15
19
  `**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
@@ -97,14 +101,14 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
97
101
  see above), but the following public fields are now signals. If your code reads them (e.g. through
98
102
  `viewChild()` or in your tests), call them (`isVisible()` instead of `isVisible`) and write them with `.set()`. Those marked _read-only_ are `computed()` signals.
99
103
  - `foehn-agenda`: `srAnnouncements`
100
- - `foehn-agenda-timeslot-panel`: `selectedTimeSlot`, `timeInputValue`, `isClosed`, `timeSlots`
101
- (_read-only_), `timeslotRemaining` (_read-only_), `canClose` (_read-only_)
104
+ - `foehn-agenda-timeslot-panel`: `selectedTimeSlot` (_read-only_), `timeInputValue` (_read-only_), `isClosed`,
105
+ `timeSlots` (_read-only_), `timeslotRemaining` (_read-only_), `canClose` (_read-only_)
102
106
  - `foehn-autocomplete`: `searchValue`, `inputHasFocus`, `hideSuggestions`, `displayedElements`,
103
107
  `notificationMessageUpdated`, `VIEW_PORT_HEIGHT` (_read-only_)
104
108
  - `foehn-multiselect-autocomplete`: `autocompleteInputValue`, `showEmptyListMessage` (_read-only_), `srAnnouncements`
105
109
  - `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes (`FoehnCheckableGroupComponent`):
106
110
  `groupedElements`
107
- - `foehn-radio`: `inputValue`
111
+ - `foehn-radio`: `inputValue` (_read-only_)
108
112
  - `foehn-confirm-modal`: `isVisible` (`content` is now a read-only field instead of a getter)
109
113
  - `foehn-date-picker`: `hostId`, `weekDays`, `weeks`, `selectedDate`, `monthListItem`
110
114
  - `foehn-dropdown-menu`: `isDropdownVisible`, `popupPosition`
@@ -112,14 +116,19 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
112
116
  - `foehn-input-address`: `country`, `locality`, `street`, `houseNumber`, `postOfficeBoxText`,
113
117
  `addressLine1`, `addressLine2` (linked to the model: they follow it and can still be set),
114
118
  `streetCustomErrors`
115
- - `foehn-input-foreign-locality`: `zipCode`, `longName`
116
- - `foehn-input-foreign-street`: `longName`
117
- - `foehn-input-date`: `day`, `month`, `year`, `datePickerModel`
119
+ - `foehn-input-foreign-locality`: `zipCode`, `longName` (linked to the model: they follow it and can still be set)
120
+ - `foehn-input-foreign-street`: `longName` (linked to the model: it follows it and can still be set)
121
+ - `foehn-input-date`: `day`, `month`, `year`, `datePickerModel` (linked to the model: they follow it and can
122
+ still be set)
118
123
  - `foehn-input-date-time`: `date`, `time` (linked to the model: they follow it and can still be set)
119
124
  - `foehn-input-time`: `hour`, `minute` (linked to the model: they follow it and can still be set)
120
- - `foehn-input-nav13`: `part2`, `part3`, `part4`
121
- - `foehn-input-textarea`: `isCharCountExceeded`, `charCountLeft`, `charCountLabel`, `ariaLiveStatus`
122
- - `foehn-list` and `foehn-table`: `currentPage`, `filteredList`
125
+ - `foehn-input-nav13`: `part2`, `part3`, `part4` (linked to the model: they follow it and can still be set)
126
+ - `foehn-input-textarea`: `isCharCountExceeded`, `charCountLeft`, `charCountLabel`, `ariaLiveStatus` (all
127
+ _read-only_; the methods `countCharLeft()` and `checkCharCountExceeded()` are removed, the count follows the
128
+ model, `max` and `displayCharCount`)
129
+ - `foehn-list`: `currentPage`, `filteredList`
130
+ - `foehn-table`: `currentPage` (linked to the model, `itemsPerPage`, `fixedPageCount` and `sort`: back to the
131
+ first page when its page no longer exists), `filteredList` (_read-only_)
123
132
  - `foehn-list-summary`: `listCopyForTable` (_read-only_), `tableConfiguration` (_read-only_)
124
133
  - `foehn-notfound`: `seconds`
125
134
  - `foehn-page`: `pageTitle`
@@ -135,8 +144,25 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
135
144
  - `captcha` (`SdkRecaptchaComponent`): `isLoaded`, `hasLoadingError`
136
145
  - `redirector` (`RedirectComponent`): `counter`
137
146
  - The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
138
- `foehn-agenda-timeslot-panel`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` and `ngOnDestroy()`
139
- of `captcha`.
147
+ `foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
148
+ `foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
149
+ - `FoehnInputComponent.onModelChange()` does nothing by default (it set `model_`): override it only to act on a new
150
+ model, e.g. to normalize it. A component deriving its fields from the model with `linkedSignal()` no longer needs
151
+ to override it, see "Creating a reusable component" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md). `model_` is set
152
+ by `FoehnInputComponent` alone, for every component: known once the model of the page has a value to display, then
153
+ following it, and staying known (`null`) when the page sets it back to `undefined`.
154
+ - A component which doesn't override `onModelChange()`, or calls `super.onModelChange()`, now handles `model_` as
155
+ those overriding it without `super` already did: it no longer replaces by `null` a model without any value to
156
+ display given by the page (e.g. `[]`, `''`) when it updates its model without any input of the user, and a
157
+ model set back to `undefined` by the page stays known.
158
+ - If one of your components reads the value of `model_`, not only `model_ !== undefined`: it is `undefined` as
159
+ long as the model of the page has had no value to display, and `null` once the page sets it back to
160
+ `undefined`.
161
+ - `modelChange` of the `foehn-input-*` components is emitted only when the component writes its model (an input of
162
+ the user, a correction of the model given by the page), not when the page changes the model: true since 19.0.0,
163
+ now documented in
164
+ [UPGRADING_V19.md](UPGRADING_V19.md#modelchange-is-emitted-only-when-the-component-writes-its-model), and on the
165
+ Lifecycle page of the documentation, which said the opposite.
140
166
  - `SdkDictionaryService.getKeySync()` reads a signal: a `computed()` or a template calling it is refreshed
141
167
  when the dictionary is (re)loaded, e.g. when the language changes.
142
168
  - `foehn-autocomplete` and `foehn-multiselect-autocomplete`: the value to display, its reset, the default
@@ -200,6 +226,14 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
200
226
  component (e.g. prefilled with `SessionInfoWithApplicationService.prefillForm()` for a connected user) is no
201
227
  longer overwritten by the model with the default country only; the default country and the clean-up of the model
202
228
  are applied after the next rendering, from the latest model.
229
+ - `foehn-input-address`: the streets and the street numbers of an address given by the page are loaded again, as in
230
+ v18. Since 19.0.0, they were only loaded once the user chose a locality and a street (the autocompletes no longer
231
+ emit `modelChange` for a model given by the page), and a locality given with its `zipCodeId` only (without
232
+ `postalLocalityHistoryId`) never loaded its streets. The lists now follow the locality and the street, whether
233
+ they come from the page or from the user. The Swiss localities are requested once the Swiss fields are displayed,
234
+ and again only when their URL changes (`swissNpaLocalityBaseUrl`, `specifiedCanton`, `withCompanyLocalities`), no
235
+ longer each time Switzerland is chosen again. The methods `userInputCountry()`, `userInputLocality()` and
236
+ `userInputStreet()` no longer take a parameter.
203
237
  - `foehn-input-address`: the deferred clean-up of the model (hidden address lines and post office box) applies
204
238
  to the latest model, it could restore a previous value (e.g. remove the default country); nothing is
205
239
  updated anymore once the component is destroyed.
@@ -208,11 +242,22 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
208
242
  prestations-ng `foehn-input-date`, `foehn-input-date-time`, `foehn-input-foreign-locality` and
209
243
  `foehn-input-foreign-street` (also in the foreign address of `foehn-input-address`), and in your project e.g. a
210
244
  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
245
+ of the page is now known (`model_`) once it has a value to display, and then follows it, before `onModelChange()`,
246
+ which can still change it. Nothing to change in your components, except one whose model can hold a value only in a part it doesn't
213
247
  display (e.g. an id) and which updates its model without any input of the user: override the new protected method
214
248
  `hasValueToDisplay()`, as `foehn-input-address` does for the country of an address only Swiss.
215
249
  - `foehn-input-date-time`: emptying its only filled field empties the model, it kept its value also in v18.
250
+ - `foehn-input-hidden`, `foehn-input-email` and `foehn-input-password` handle their model as `foehn-input-text` does:
251
+ a number `0` given by the page (e.g. a number field in Java bound to a `foehn-input-hidden`) is kept, it was
252
+ replaced by `null`, which was then saved. An empty string is replaced by `null` at once, instead of after a timer
253
+ that `fixture.whenStable()` didn't wait for, and that could overwrite a value given by the page meanwhile. Their
254
+ public field `timeoutReference` is removed.
255
+ - `foehn-input-textarea` replaces by `null` an empty string given by the page, as the other text fields do. Its
256
+ character count follows a change of `max` or `displayCharCount` at once: it kept the previous count until the next
257
+ input, and the textarea stayed `aria-invalid` once the count was no longer displayed.
258
+ - `foehn-radio`: `inputValue` follows a change of `elementValue` or `elementValueIdentity`, not only of the model.
259
+ - `foehn-input-time` replaces by `null` an empty string given by the page, as the other text fields do: the backend
260
+ rejected it (`@ValidStringTime` accepts `null`, not `''`), although the user had entered nothing.
216
261
  - 🚨 `ObjectHelper.hasAnyValue()` and `ObjectHelper.isEmpty()`: a number (`0` included), a boolean (`false`
217
262
  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
263
  or an array (e.g. `{ checked: false }`, `[0, 0]`). Only `null`, `undefined`, `''` and the arrays and objects
package/GOOD_PRACTICES.md CHANGED
@@ -749,31 +749,34 @@ Your component must:
749
749
  1. `selector` should start with `"app-..."` to avoid possible naming conflicts
750
750
  2. have a `providers`
751
751
  3. extend `FoehnInputComponent`, to which you must give your data model
752
- 4. spread the attributes of your data model in public **signals** used in
753
- your HTML
752
+ 4. spread the attributes of your data model in public **linked signals** (`linkedSignal()`) used
753
+ in your HTML: they follow the model of your page, and your sub-components change them
754
754
  5. implement an `update` function (here it will be `updateDate`) calling `updateNgModel` to
755
755
  keep your data model synchronized with your page
756
756
  6. implement a `handleUserInput` function calling `handleChange` to keep
757
757
  notifying the parent of the behavior changes of your component
758
- 7. implement an `onModelChange` function to correctly initialize the
759
- signals corresponding to your model
758
+ 7. not override the `onModelChange` function for your linked signals, which already follow the
759
+ model: override it only to act on a new model of your page (e.g. to normalize it)
760
760
  8. implement a `getValidValue` function to rebuild your data model before sending it
761
761
  back to your page, and return `null` if all the attributes of your object are empty (this
762
- is to keep Java happy)
762
+ is to keep Java happy), once your model is known (`model_ !== undefined`): it is once the model of
763
+ your page has had a value to display, so that a model without any value (e.g. `[]`) is never
764
+ replaced by `null` without an input of the user
763
765
 
764
766
  > 🚨 **standalone / signals** points to respect:
765
767
  >
766
768
  > - **No `multi: true`** in the `providers` (removed since the standalone migration).
767
769
  > - The `imports` of the component are declared **directly** in the `@Component` decorator. Each
768
770
  > component loads what it needs (see `foehn-input-date` in this project).
769
- > - The state displayed by the component is held in **signals** (point 4): `onModelChange` is
770
- > called when the model changes, sometimes outside of an event of the template, and a plain field
771
- > would then not be displayed without zone.js.
771
+ > - The state displayed by the component is held in **linked signals** (point 4), derived from the
772
+ > model: a plain field would not be displayed without zone.js, and a `signal()` filled by
773
+ > `onModelChange` (called by an `effect()`) would follow the model only at the next change
774
+ > detection.
772
775
 
773
776
  `input-date.component.ts`
774
777
 
775
778
  ```ts
776
- import { Component, forwardRef, signal } from '@angular/core';
779
+ import { Component, forwardRef, linkedSignal } from '@angular/core';
777
780
 
778
781
  import { FoehnInputComponent } from '../foehn-input/foehn-input.component';
779
782
  import { FoehnInputNumberComponent } from '../foehn-input/foehn-input-number.component';
@@ -802,10 +805,23 @@ import { SdkDictionaryPipe } from '../sdk-dictionary/sdk-dictionary.pipe';
802
805
  export class InputDateComponent extends FoehnInputComponent<number[]> {
803
806
  // point (3): extends FoehnInputComponent<number[]>
804
807
 
805
- // point (4): the attributes of your model spread in public signals
806
- readonly day = signal<string | null>(null);
807
- readonly month = signal<string | null>(null);
808
- readonly year = signal<string | null>(null);
808
+ // point (4): the attributes of your model spread in public linked signals. A new model of your
809
+ // page resets them, a model too short to hold a date keeps them (previous value).
810
+ readonly day = linkedSignal<number[] | null | undefined, string | null>({
811
+ source: this.model,
812
+ computation: (value, previous) =>
813
+ this.getDatePart(value, 2, previous?.value),
814
+ });
815
+ readonly month = linkedSignal<number[] | null | undefined, string | null>({
816
+ source: this.model,
817
+ computation: (value, previous) =>
818
+ this.getDatePart(value, 1, previous?.value),
819
+ });
820
+ readonly year = linkedSignal<number[] | null | undefined, string | null>({
821
+ source: this.model,
822
+ computation: (value, previous) =>
823
+ this.getDatePart(value, 0, previous?.value),
824
+ });
809
825
 
810
826
  // point (5)
811
827
  updateDate(): void {
@@ -823,18 +839,7 @@ export class InputDateComponent extends FoehnInputComponent<number[]> {
823
839
  }
824
840
  }
825
841
 
826
- // point (7)
827
- override onModelChange(value: number[] | null): void {
828
- if (value && value.length > 2) {
829
- this.year.set(this.toString(value[0]));
830
- this.month.set(this.toString(value[1]));
831
- this.day.set(this.toString(value[2]));
832
- } else if (!value) {
833
- this.year.set(null);
834
- this.month.set(null);
835
- this.day.set(null);
836
- }
837
- }
842
+ // point (7): no onModelChange(), the linked signals of point (4) already follow the model
838
843
 
839
844
  // point (8)
840
845
  getValidValue(): number[] | null | undefined {
@@ -858,9 +863,25 @@ export class InputDateComponent extends FoehnInputComponent<number[]> {
858
863
  }
859
864
 
860
865
  // ...code
866
+
867
+ private getDatePart(
868
+ value: number[] | null | undefined,
869
+ index: number,
870
+ previous: string | null | undefined,
871
+ ): string | null {
872
+ if (value && value.length > 2) {
873
+ return this.toString(value[index]);
874
+ }
875
+ return value ? (previous ?? null) : null;
876
+ }
861
877
  }
862
878
  ```
863
879
 
880
+ > 💡 A field that only reads a property of the model can use the short form, e.g.
881
+ > `readonly street = linkedSignal(() => this.model()?.street ?? null);` (see `foehn-input-address`).
882
+ > It resets the field at every new model: use the form `{ source, computation }`, as above, when a
883
+ > field must keep its value on a partial model.
884
+
864
885
  Each `foehn-input-*` used in your view must:
865
886
 
866
887
  1. have an `id` concatenating the call to the `buildId()` function and the name of the attribute of your object
package/UPGRADING_V19.md CHANGED
@@ -1446,6 +1446,23 @@ When using `IntelliJ`, you can run code inspection on your project to fix deprec
1446
1446
  - IntelliJ window menu, go to: `Code > Analyze code > Run inspection by name...` (or **Ctrl+Alt+Maj+i**) and type `Deprecated symbol used`.
1447
1447
  - Or select your project in your project panel and `right click` on it then `Analyze > Run inspection by name...` (or **Ctrl+Alt+Maj+i**) and type `Deprecated symbol used`.
1448
1448
 
1449
+ ### `(modelChange)` is emitted only when the component writes its model
1450
+
1451
+ In v18, a `foehn-input-*` component emitted `modelChange` again each time the page gave it a model, the same value
1452
+ included: the form loaded from the backend, a prefill, a reset... (with `undefined` at the initialization). Since
1453
+ 19.0.0, the model of the components is a signal (`model()`), and `modelChange` is emitted only when the component
1454
+ writes its model, with a new value:
1455
+
1456
+ - at each input of the user, at once (`userInput` comes after a debounce);
1457
+ - when the component corrects the model the page gave it, e.g. `''` replaced by `null` in the text fields, a NAVS
1458
+ formatted as `756.xxxx.xxxx.xx`, the default country of an address, the `defaultElementValue` of a `foehn-select`.
1459
+
1460
+ It is no longer emitted when the page changes the model itself, which `[(model)]` doesn't need. Search your templates
1461
+ for `(modelChange)` on a `foehn-` component: a handler which also had to react to a model set by the page (e.g. to
1462
+ fill another field once the form is loaded, often behind a guard on `undefined`) is no longer called for it. Do that
1463
+ work where the page writes the form: after its loading (`GesdemEventService.formInitializationObservable()`, which
1464
+ emits the loaded form), after a prefill, after a reset.
1465
+
1449
1466
  ### Strict mode (optional when migrating large projects but recommended)
1450
1467
 
1451
1468
  - In your `tsconfig.json` file, add `"strict": true` in `compilerOptions` and remove `alwaysStrict`, `noImplicitThis`, `strictBindCallApply` and `strictFunctionTypes` as they are already included in `strict` mode.