@dsivd/prestations-ng 19.2.0-beta.2 → 19.2.0-beta.21
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/ANGULAR_SIGNALS.md +4 -0
- package/CHANGELOG.md +396 -0
- package/CONTRIBUTING.md +74 -4
- package/ESLINT_PLUGIN.md +103 -8
- package/GOOD_PRACTICES.md +731 -380
- package/INTRODUCTION_ANGULAR_SIGNALS.md +199 -154
- package/UPGRADING_V18.md +5 -5
- package/UPGRADING_V19.md +439 -18
- package/eslint/configs/spec-ts-recommended.mjs +34 -0
- package/eslint/configs/template-recommended.mjs +2 -0
- package/eslint/configs/template-rules.mjs +11 -2
- package/eslint/configs/ts-recommended.mjs +6 -0
- package/eslint/configs/ts-rules.mjs +6 -2
- package/eslint/form-reads.mjs +63 -0
- package/eslint/index.mjs +17 -0
- package/eslint/rules/index.mjs +4 -0
- package/eslint/rules/no-direct-signal-mutation.mjs +58 -20
- package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
- package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/eslint/rules/require-model-change.mjs +89 -0
- package/eslint/template-ast.mjs +12 -2
- package/fesm2022/dsivd-prestations-ng.mjs +2766 -2073
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -2
- package/schematics/migration-collection.json +5 -0
- package/schematics/ng-add/index.js +2 -4
- package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
- package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
- package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
- package/schematics/utility/form-signal/class-migration.js +396 -0
- package/schematics/utility/form-signal/edits.js +34 -0
- package/schematics/utility/form-signal/form-signal-migration.js +184 -0
- package/schematics/utility/form-signal/page-classes.js +129 -0
- package/schematics/utility/form-signal/template-migration.js +666 -0
- package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
- package/src/eslint/configs/__tests__/configs.test.mjs +46 -2
- package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
- package/src/eslint/configs/template-recommended.mjs +2 -0
- package/src/eslint/configs/template-rules.mjs +11 -2
- package/src/eslint/configs/ts-recommended.mjs +6 -0
- package/src/eslint/configs/ts-rules.mjs +6 -2
- package/src/eslint/form-reads.mjs +63 -0
- package/src/eslint/index.mjs +17 -0
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
- package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -0
- package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
- package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
- package/src/eslint/rules/index.mjs +4 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +58 -20
- package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -0
- package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/src/eslint/rules/require-model-change.mjs +89 -0
- package/src/eslint/template-ast.mjs +12 -2
- package/types/dsivd-prestations-ng.d.ts +652 -240
- package/dsivd-prestations-ng-19.2.0-beta.2.tgz +0 -0
package/ANGULAR_SIGNALS.md
CHANGED
|
@@ -866,6 +866,10 @@ this.address.update((current) => ({
|
|
|
866
866
|
...current,
|
|
867
867
|
locality: { ...current.locality, name: 'newName' },
|
|
868
868
|
}));
|
|
869
|
+
|
|
870
|
+
// 🟢 The same with prestations-ng, at any depth: the objects along the path are copied,
|
|
871
|
+
// the path is checked by TypeScript, and the signal notifies only when the value changes
|
|
872
|
+
ObjectPathHelper.patchSignal(this.address, ['locality', 'name'], 'newName');
|
|
869
873
|
```
|
|
870
874
|
|
|
871
875
|
#### 8b. Two-way binding directly on an array element inside `@for`
|
package/CHANGELOG.md
CHANGED
|
@@ -8,11 +8,389 @@
|
|
|
8
8
|
|
|
9
9
|
## [19.2.0] - should be aligned with prestations-be 19.2.x
|
|
10
10
|
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- [object-path.helper.ts](projects/prestations-ng/src/helpers/object-path.helper.ts)
|
|
14
|
+
- New `ObjectPathHelper`: reads and writes a value at a path of any object, without modifying it: a write copies
|
|
15
|
+
the objects and arrays along the path (with their prototype), keeps the others as they are, and gives the object
|
|
16
|
+
itself when the value is already there.
|
|
17
|
+
- `get(object, path)`, `patch(object, path, value)` and `patchSignal(signal, path, value)` (for a signal holding
|
|
18
|
+
an object: its readers are notified only when the value changes) take a path checked by TypeScript, typed with
|
|
19
|
+
the new `ObjectPath<T>` (`['address', 'street']`, `['children', 0, 'firstName']`, the paths of each member of a
|
|
20
|
+
union) and `ObjectPathValue<T, P>`.
|
|
21
|
+
- `getByKeys(object, keys)` and `patchByKeys(object, keys, value)` take keys known at runtime only
|
|
22
|
+
(`'address.street'`, or a list of keys), not checked.
|
|
23
|
+
- `patchForm()`, `patchItem()`, `PendingUploadService`, the custom errors of the street of `foehn-input-address`
|
|
24
|
+
and the elements of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes use it.
|
|
25
|
+
- `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
|
|
26
|
+
classes and their templates (see the 🚨 entries below and
|
|
27
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
|
|
28
|
+
migrate, and running it again changes nothing.
|
|
29
|
+
- 🚨 ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
|
|
30
|
+
[`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
|
|
31
|
+
`configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
|
|
32
|
+
is lost; a component always disabled, `foehn-input-hidden`, `foehn-table` and a component listening to
|
|
33
|
+
`(userInput)` excepted), and a `@for` over a list of the form tracked by its item while its rows edit it (the field loses the focus
|
|
34
|
+
at every input).
|
|
35
|
+
|
|
36
|
+
- [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
|
|
37
|
+
- New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
|
|
38
|
+
`LenientLocalDate` of prestations-be), to type the date fields of your forms, e.g.
|
|
39
|
+
`birthDate: FoehnDateModel | null = null;`.
|
|
40
|
+
- `DateHelper.isValid()`, `isToday()` and `toDayjsFromNumberArray()` accept it, `null` and `undefined`
|
|
41
|
+
included: no cast in a strict project. A date with a part not entered is still neither valid nor today, and
|
|
42
|
+
gives `null`.
|
|
43
|
+
- [foehn-date-time-model.type.ts](projects/prestations-ng/src/foehn-input-date-time/foehn-date-time-model.type.ts)
|
|
44
|
+
- New `FoehnDateTimeModel` type, the model of `foehn-input-date-time` (`(number | null)[]`: year, month, day,
|
|
45
|
+
hour, minute, the JSON of a `LenientLocalDateTime` of prestations-be).
|
|
46
|
+
- The `displayDate` pipe, `DateHelper.toDateFromNumberArray()`, `arrayToDisplayDateDMY()`, `isValid()` and
|
|
47
|
+
`isToday()` accept it, as well as a `FoehnDateModel`. The new `DateHelper.hasTime()` tells whether a date-time
|
|
48
|
+
has its time entered.
|
|
49
|
+
`DateHelper.leftPad()` accepts `null` and `undefined` (it already returned `''`).
|
|
50
|
+
- [eslint/configs/spec-ts-recommended.mjs](projects/prestations-ng/src/eslint/configs/spec-ts-recommended.mjs)
|
|
51
|
+
- New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
|
|
52
|
+
`**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
|
|
53
|
+
the `HttpTestingController` and of the helpers of the specs. It needs `@vitest/eslint-plugin` in the
|
|
54
|
+
devDependencies of your project, only when you use it: 1.6.27 with the TypeScript 5.9 of Angular 21, later
|
|
55
|
+
versions need TypeScript 6. See
|
|
56
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#migrate-to-eslint-flat-configuration).
|
|
57
|
+
- [foehn-bo-multi-upload.component.ts](projects/prestations-ng/src/foehn-upload/foehn-bo-multi-upload/foehn-bo-multi-upload.component.ts)
|
|
58
|
+
- New `localUpload` input. When set to `true`, selected files are kept purely local
|
|
59
|
+
(as `DocumentReferenceWithFile`, no `uploadUrl()` call) so they can be cancelled before
|
|
60
|
+
being sent. Files show up immediately in the list with a "pending" indicator (dictionary
|
|
61
|
+
key `foehn-uploader.pending-label`, French default provided) since they're not uploaded
|
|
62
|
+
yet. It is your responsibility to upload/delete them at save time,
|
|
63
|
+
e.g. via the new
|
|
64
|
+
[document-changes.helper.ts](projects/prestations-ng/src/foehn-upload/document-changes.helper.ts)
|
|
65
|
+
(`splitDocumentChanges`) which computes `filesToAdd`/`documentsToDelete` from the model.
|
|
66
|
+
- The default (direct upload) mode is unchanged.
|
|
67
|
+
- New `maxFileSizeInMo` input: a client-side, per-file size limit that doesn't depend on
|
|
68
|
+
the `fileMaxSizeInBytesByFormKey` server configuration (useful for consumers that don't
|
|
69
|
+
expose that config yet). When both are set, the smallest limit applies. A file too big gets
|
|
70
|
+
the usual `413` error, which can be customized with `customErrors` (`{fileName}`,
|
|
71
|
+
`{fileMaxSize}`).
|
|
72
|
+
- New `chooseButtonStyleModifier` input, appended to the choose button's CSS classes
|
|
73
|
+
(e.g. `btn-sm`), mirroring the same input already available on other uploaders.
|
|
74
|
+
|
|
75
|
+
- [foehn-input-address.component.ts](projects/prestations-ng/src/foehn-address/foehn-input-address.component.ts)
|
|
76
|
+
- Added `streetAllowCustomValue` input to control whether the street field allows custom values (defaults to `true`).
|
|
77
|
+
- Added `swissNpaLocalityBaseUrl` input to control the base URL for Swiss NPA localities (defaults to `'api/refinf/locality'`).
|
|
78
|
+
|
|
79
|
+
- [foehn-navigation.component.html](projects/prestations-ng/src/foehn-navigation/foehn-navigation/foehn-navigation.component.html)
|
|
80
|
+
- [foehn-simple-navigation.component.html](projects/prestations-ng/src/foehn-navigation/foehn-simple-navigation/foehn-simple-navigation.component.html)
|
|
81
|
+
- while the page targeted by "next", "transmit" or "previous" is loading for more than 200 ms (e.g. lazy loaded
|
|
82
|
+
route), the clicked button displays a spinner with the new `loadingLabel` input (dictionary key
|
|
83
|
+
`foehn-navigation.loading.label`, "Chargement...") and the navigation buttons are disabled (`aria-disabled`;
|
|
84
|
+
clicks are ignored from the start of the navigation); a live `output` region announces the loading to screen
|
|
85
|
+
readers (also in 18.3.15)
|
|
86
|
+
- this state is exposed by read-only signals: `pendingNavigationDirection`, `loadingDirection`, `isNavigating`,
|
|
87
|
+
`isLoading`, `isLoadingNext` and `isLoadingPrevious`
|
|
88
|
+
- [foehn-navigation.service.ts](projects/prestations-ng/src/foehn-navigation/foehn-navigation.service.ts)
|
|
89
|
+
- new method `pendingNavigationDirection()`: direction of the navigation started with `next()` or `previous()`
|
|
90
|
+
until it ends, `null` otherwise (also in 18.3.15)
|
|
91
|
+
|
|
11
92
|
### Changed
|
|
12
93
|
|
|
13
94
|
Library now runs as strict mode, which may cause some errors to appear in your project after updating.
|
|
14
95
|
Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information.
|
|
15
96
|
|
|
97
|
+
- [foehn-list-summary.component.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-summary.component.ts)
|
|
98
|
+
- `FoehnListSummaryComponent` is now generic: `FoehnListSummaryComponent<T extends FoehnListItem>`,
|
|
99
|
+
so the model, `getListItemTitle` and `listItemDescriptions` are typed with your own item class
|
|
100
|
+
instead of the base `FoehnListItem`
|
|
101
|
+
- [foehn-list-item-description.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-item-description.ts)
|
|
102
|
+
- 🚨 `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
|
|
103
|
+
`getFormattedValue(item: T)` and `hideIfEmpty(item: T)` receive your item type directly, no cast needed.
|
|
104
|
+
Replace `FoehnListItemDescription[]` with `FoehnListItemDescription<MyItem>[]` in your project.
|
|
105
|
+
- [uploader.helper.ts](projects/prestations-ng/src/foehn-upload/uploader.helper.ts)
|
|
106
|
+
- 🚨 `UploaderHelper.addCustomErrorOrDefault()` takes the limits of the uploader in an object (`UploaderErrorLimits`,
|
|
107
|
+
all optional) instead of its last three parameters:
|
|
108
|
+
`addCustomErrorOrDefault(name, errors, errorCode, fileName, customErrors, { overrideAcceptedExtensions, overrideMaxFileNameLength, overrideIllegalCharacters, maxFileSizeInMo })`.
|
|
109
|
+
The custom error 413 returned by the server now also displays the `maxFileSizeInMo` limit of
|
|
110
|
+
`foehn-bo-multi-upload`.
|
|
111
|
+
- [foehn-modal.component.ts](projects/prestations-ng/src/foehn-modal/foehn-modal.component.ts)
|
|
112
|
+
- 🚨 `modalSize` is now typed with the new `FoehnModalSize` type
|
|
113
|
+
(`'' | 'modal-sm' | 'modal-md' | 'modal-lg' | 'modal-xl'`) instead of `string`, as are `HelpModal.modalSize`
|
|
114
|
+
and therefore the `helpModal` of the `foehn-input-*` components. Other values, such as `modal-xs`, are not
|
|
115
|
+
Bootstrap classes, had no effect and no longer compile: replace them with `modal-md` to keep the same size
|
|
116
|
+
(removing them in a `HelpModal` would fall back to `modal-lg`).
|
|
117
|
+
- [foehn-table.component.ts](projects/prestations-ng/src/foehn-table/foehn-table.component.ts)
|
|
118
|
+
- 🚨 `columnsConfiguration` is now an `input()` instead of a `model()`: the table never changes it. The
|
|
119
|
+
two-way binding `[(columnsConfiguration)]` and the `columnsConfigurationChange` output no longer exist, and
|
|
120
|
+
`columnsConfiguration.set()` no longer compiles: bind it with `[columnsConfiguration]`.
|
|
121
|
+
- 🚀 **prestations-ng is now zoneless**: its components no longer need zone.js to be refreshed. They keep
|
|
122
|
+
working in an application using zone.js, and your application can now drop zone.js, see
|
|
123
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#zoneless-optional-but-recommended).
|
|
124
|
+
- the state displayed by the components is held by signals (`signal()`, `computed()`, `linkedSignal()`)
|
|
125
|
+
- what was waiting for `NgZone.onMicrotaskEmpty` or a `setTimeout()` to reach the rendered DOM (focus,
|
|
126
|
+
scroll, value displayed by the autocompletes, default values...) now uses `afterNextRender()`
|
|
127
|
+
- the short asynchronous work of the components is tracked with `PendingTasks`, so that
|
|
128
|
+
`ApplicationRef.whenStable()` (and `fixture.whenStable()` in your tests) waits for it: the debounced
|
|
129
|
+
`userInput` output of the `foehn-input-*` components, the debounced time of `foehn-input-date-time`,
|
|
130
|
+
the locale of `foehn-date-picker`, the default country and the sanitized model of `foehn-input-address`
|
|
131
|
+
- `providePrestationsNgCore()` now provides `provideBrowserGlobalErrorListeners()`: without zone.js, the
|
|
132
|
+
errors thrown in a timer or a promise still reach your `ErrorHandler`
|
|
133
|
+
- 🚨 **The inputs and outputs of the components are unchanged** (except `columnsConfiguration` of `foehn-table`,
|
|
134
|
+
see above), but the following public fields are now signals. If your code reads them (e.g. through
|
|
135
|
+
`viewChild()` or in your tests), call them (`isVisible()` instead of `isVisible`) and write them with `.set()`. Those marked _read-only_ are `computed()` signals.
|
|
136
|
+
- `foehn-agenda`: `srAnnouncements`
|
|
137
|
+
- `foehn-agenda-timeslot-panel`: `selectedTimeSlot` (_read-only_), `timeInputValue` (_read-only_), `isClosed`,
|
|
138
|
+
`timeSlots` (_read-only_), `timeslotRemaining` (_read-only_), `canClose` (_read-only_)
|
|
139
|
+
- `foehn-autocomplete`: `searchValue`, `inputHasFocus`, `hideSuggestions`, `displayedElements`,
|
|
140
|
+
`notificationMessageUpdated`, `VIEW_PORT_HEIGHT` (_read-only_)
|
|
141
|
+
- `foehn-multiselect-autocomplete`: `autocompleteInputValue`, `showEmptyListMessage` (_read-only_), `srAnnouncements`
|
|
142
|
+
- `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes (`FoehnCheckableGroupComponent`):
|
|
143
|
+
`groupedElements`
|
|
144
|
+
- `foehn-radio`: `inputValue` (_read-only_)
|
|
145
|
+
- `foehn-confirm-modal`: `isVisible` (`content` is now a read-only field instead of a getter)
|
|
146
|
+
- `foehn-date-picker`: `hostId`, `weekDays`, `weeks`, `selectedDate`, `monthListItem`
|
|
147
|
+
- `foehn-dropdown-menu`: `isDropdownVisible`, `popupPosition`
|
|
148
|
+
- `foehn-header`: `connectedEsMenu` (_read-only_)
|
|
149
|
+
- `foehn-input-address`: `country`, `locality`, `street`, `houseNumber`, `postOfficeBoxText`,
|
|
150
|
+
`addressLine1`, `addressLine2` (linked to the model: they follow it and can still be set),
|
|
151
|
+
`streetCustomErrors`
|
|
152
|
+
- `foehn-input-foreign-locality`: `zipCode`, `longName` (linked to the model: they follow it and can still be set)
|
|
153
|
+
- `foehn-input-foreign-street`: `longName` (linked to the model: it follows it and can still be set)
|
|
154
|
+
- `foehn-input-date`: `day`, `month`, `year`, `datePickerModel` (linked to the model: they follow it and can
|
|
155
|
+
still be set)
|
|
156
|
+
- `foehn-input-date-time`: `date`, `time` (linked to the model: they follow it and can still be set)
|
|
157
|
+
- `foehn-input-time`: `hour`, `minute` (linked to the model: they follow it and can still be set)
|
|
158
|
+
- `foehn-input-nav13`: `part2`, `part3`, `part4` (linked to the model: they follow it and can still be set)
|
|
159
|
+
- `foehn-input-textarea`: `isCharCountExceeded`, `charCountLeft`, `charCountLabel`, `ariaLiveStatus` (all
|
|
160
|
+
_read-only_; the methods `countCharLeft()` and `checkCharCountExceeded()` are removed, the count follows the
|
|
161
|
+
model, `max` and `displayCharCount`)
|
|
162
|
+
- `foehn-list`: `currentPage`, `filteredList`
|
|
163
|
+
- `foehn-table`: `currentPage` (linked to the model, `itemsPerPage`, `fixedPageCount` and `sort`: back to the
|
|
164
|
+
first page when its page no longer exists), `filteredList` (_read-only_)
|
|
165
|
+
- `foehn-list-summary`: `listCopyForTable` (_read-only_), `tableConfiguration` (_read-only_)
|
|
166
|
+
- `foehn-notfound`: `seconds`
|
|
167
|
+
- `foehn-page`: `pageTitle`
|
|
168
|
+
- `foehn-page-counter`: `isStable` (was an `Observable<boolean>`)
|
|
169
|
+
- `foehn-page-modal`: `wrongPublicModalVisible`, `formattedPublicsCibles`
|
|
170
|
+
- `foehn-picture-upload`: `pictureToCrop`, `croppedPictureAsBlob`, `loading`
|
|
171
|
+
- `foehn-status-progress-bar`: `isTransmitted`
|
|
172
|
+
- `gesdem-action-recovery-login`: `demandeNotFound`, `rateLimited`, `rateLimitCounter`, `otpRecipient`,
|
|
173
|
+
`otp`
|
|
174
|
+
- `gesdem-action-recovery-registration`: `mailSent`, `model` (replaced by the new `updateModel()` method,
|
|
175
|
+
never mutated)
|
|
176
|
+
- `epayment-form` (`SdkEpaymentComponent`): `failureModalDisplayed`, `redirectModalDisplayed`
|
|
177
|
+
- `captcha` (`SdkRecaptchaComponent`): `isLoaded`, `hasLoadingError`
|
|
178
|
+
- `redirector` (`RedirectComponent`): `counter`
|
|
179
|
+
- 🚨 `AbstractPageComponent`: `reference` is now a signal. Read it with `reference()` in your pages and their
|
|
180
|
+
templates, and write it with `reference.set()`. A template, a `computed()` or an `effect()` reading it follows the
|
|
181
|
+
reference, also when your page sets it, without `markForCheck()`. A page declaring its own `reference` field no
|
|
182
|
+
longer compiles: remove it. The `ng update` migration rewrites your pages, see
|
|
183
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#reference-of-your-pages-is-a-signal-since-1920).
|
|
184
|
+
- 🚨 ESLint: `configs.tsRecommended` enables `@typescript-eslint/restrict-template-expressions`. A template literal
|
|
185
|
+
only takes strings, numbers, booleans, `null`, `undefined`, `any` and `RegExp`: a signal not called
|
|
186
|
+
(`` `api/${this.reference}` ``) or an object turned into text by its `toString()` is reported. See
|
|
187
|
+
[ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#the-typescript-counterpart).
|
|
188
|
+
- 🚨 `AbstractPageComponent`: `form` is now a signal (`WritableSignal<T | null | undefined>`). Read it with `form()`,
|
|
189
|
+
never modify its value in place: write it with the new `patchForm(path, value)`
|
|
190
|
+
(`[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`), `form.set()` or `form.update()`. A
|
|
191
|
+
template, a `computed()` or an `effect()` reading it follows every input of the user, and no `markForCheck()` is
|
|
192
|
+
needed after a write anymore. The `ng update` migration rewrites your pages, see
|
|
193
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920).
|
|
194
|
+
- 🚨 `AbstractListDetailPageComponent`: the abstract `getListPath()` (the path of the list in the form) replaces the
|
|
195
|
+
abstract `getList()`, which reads the list at that path. `list`, `itemIndex` and `itemToEdit` are now signals. The
|
|
196
|
+
item edited is written with the new `patchItem(path, value)`, `updateItem(update)` (several fields in one write)
|
|
197
|
+
and `setItem(item)`. A new item is added without modifying the list of the form in place.
|
|
198
|
+
- `PendingUploadService` writes the documents uploaded with the form into a new form, instead of modifying the form
|
|
199
|
+
in place.
|
|
200
|
+
- 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) sees through the
|
|
201
|
+
TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
|
|
202
|
+
now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
|
|
203
|
+
`[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
|
|
204
|
+
- The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
|
|
205
|
+
`foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
|
|
206
|
+
`foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
|
|
207
|
+
- `FoehnInputComponent.onModelChange()` does nothing by default (it set `model_`): override it only to act on a new
|
|
208
|
+
model, e.g. to normalize it. A component deriving its fields from the model with `linkedSignal()` no longer needs
|
|
209
|
+
to override it, see "Creating a reusable component" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md). `model_` is set
|
|
210
|
+
by `FoehnInputComponent` alone, for every component: known once the model of the page has a value to display, then
|
|
211
|
+
following it, and staying known (`null`) when the page sets it back to `undefined`.
|
|
212
|
+
- A component which doesn't override `onModelChange()`, or calls `super.onModelChange()`, now handles `model_` as
|
|
213
|
+
those overriding it without `super` already did: it no longer replaces by `null` a model without any value to
|
|
214
|
+
display given by the page (e.g. `[]`, `''`) when it updates its model without any input of the user, and a
|
|
215
|
+
model set back to `undefined` by the page stays known.
|
|
216
|
+
- If one of your components reads the value of `model_`, not only `model_ !== undefined`: it is `undefined` as
|
|
217
|
+
long as the model of the page has had no value to display, and `null` once the page sets it back to
|
|
218
|
+
`undefined`.
|
|
219
|
+
- `modelChange` of the `foehn-input-*` components is emitted only when the component writes its model (an input of
|
|
220
|
+
the user, a correction of the model given by the page), not when the page changes the model: true since 19.0.0,
|
|
221
|
+
now documented in
|
|
222
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#modelchange-is-emitted-only-when-the-component-writes-its-model), and on the
|
|
223
|
+
Lifecycle page of the documentation, which said the opposite.
|
|
224
|
+
- 🚨 The `onModelChange()` methods which were not the hook of `FoehnInputComponent` are removed or renamed (they are
|
|
225
|
+
not called by the model anymore):
|
|
226
|
+
- `foehn-date-picker-button`: `model_`, `onModelChange()` and `updateNgModel()` are removed, they had no effect
|
|
227
|
+
(`model_` was never read).
|
|
228
|
+
- `foehn-date-picker`: `model_` is removed (never read), `onModelChange()` is now private (`syncWithModel()`).
|
|
229
|
+
- `numberCurrencyFormatter`: `onModelChange()` is now private (`formatModel()`), and the directive no longer
|
|
230
|
+
listens to the `modelChange` of its host: its `effect()` already formats every model, the ones written by the
|
|
231
|
+
host were formatted twice.
|
|
232
|
+
- `SdkDictionaryService.getKeySync()` reads a signal: a `computed()` or a template calling it is refreshed
|
|
233
|
+
when the dictionary is (re)loaded, e.g. when the language changes.
|
|
234
|
+
- `foehn-autocomplete` and `foehn-multiselect-autocomplete`: the value to display, its reset, the default
|
|
235
|
+
values and the focus after a click on a suggestion are applied after the next rendering instead of in a
|
|
236
|
+
`setTimeout()`.
|
|
237
|
+
- Unit tests of the library: Karma and Jasmine are replaced by Vitest 4 in browser mode (Playwright,
|
|
238
|
+
headless Chromium), see [CONTRIBUTING.md](CONTRIBUTING.md#unit-testing).
|
|
239
|
+
- `core-js` is no longer a peer dependency: prestations-ng no longer imports it since 19.1.1, see
|
|
240
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#core-js-is-no-longer-needed-since-1920).
|
|
241
|
+
- `ng add @dsivd/prestations-ng` adds `iban` and `dayjs` (the CommonJS dependencies of prestations-ng) to the
|
|
242
|
+
`allowedCommonJsDependencies` of `angular.json`, instead of `core-js/modules/es.array.includes`, `iban` and
|
|
243
|
+
`zone.js/dist/zone-error`, and no longer sets `allowSyntheticDefaultImports` (implied by the `tsconfig.json` of
|
|
244
|
+
Angular 21: `"module": "preserve"` or `"moduleResolution": "bundler"`).
|
|
245
|
+
- `GOOD_PRACTICES.md` and `INTRODUCTION_ANGULAR_SIGNALS.md` are now in English, like the rest of the
|
|
246
|
+
documentation: the titles of their sections, and so their anchors, have changed.
|
|
247
|
+
|
|
248
|
+
### Deprecated
|
|
249
|
+
|
|
250
|
+
- `AbstractMenuPageComponent.ngZone` is no longer used and will be removed: `NgZone.onStable` never emits
|
|
251
|
+
without zone.js.
|
|
252
|
+
- `ObjectHelper.getNestedProperty(obj, key)` will be removed: use `ObjectPathHelper.getByKeys(obj, key)`, which it
|
|
253
|
+
now calls (see Fixed).
|
|
254
|
+
|
|
255
|
+
### Fixed
|
|
256
|
+
|
|
257
|
+
- 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
|
|
258
|
+
`elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
|
|
259
|
+
autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
|
|
260
|
+
a class, is no longer `undefined`, and a nested key is no longer looked up in another nested object holding the same
|
|
261
|
+
key (`'country.name'` gave the `name` of the first nested object having one). A value `null` is no longer
|
|
262
|
+
`undefined` either: an element `{ value: null }` is now selected by a model `null` (e.g. sent by the backend), no
|
|
263
|
+
longer by a model `undefined` (e.g. a field missing from the JSON), and choosing it writes `null` into the model, no
|
|
264
|
+
longer `undefined`.
|
|
265
|
+
- 🚨 `DateHelper.isValid()` also checks the time of a date-time (5 parts or more, e.g. the model of
|
|
266
|
+
`foehn-input-date-time`), as `LenientLocalDateTime.isValid()` of prestations-be: an hour (0 to 23) and a minute (0
|
|
267
|
+
to 59) are required. It only checked the date: a date-time without its time, or at 25:00, was valid. Check your
|
|
268
|
+
calls on a date-time. `isToday()` still considers only the date.
|
|
269
|
+
- The `displayDate` pipe, `DateHelper.toDateFromNumberArray()` and `arrayToDisplayDateDMY()` no longer give a wrong
|
|
270
|
+
date for a date with a part not entered (e.g. a draft saved with an incomplete date): `[2020, null, null]` was
|
|
271
|
+
displayed `30.11.2019`, it now gives nothing. A date-time without its time gives only the date (it displayed
|
|
272
|
+
`00:00:00`), and an empty array gives nothing (it threw an error). `DateHelper.isToday()`: a date which does not
|
|
273
|
+
exist is no longer today (the 30.02.2026 was the 02.03.2026).
|
|
274
|
+
- `AbstractPageComponent` and `AbstractPageFromMenuComponent`: a second click on "next" or "transmit" while the next
|
|
275
|
+
page is loading (lazy loaded route, resolver, async guard) no longer saves again and skips the next page:
|
|
276
|
+
`send()`, `sendAndTransmit()` and `transmit()` are ignored until the navigation to the next page ends. Pages
|
|
277
|
+
overriding `onFormSent()` should call the new protected method `navigateToNextPage()` instead of
|
|
278
|
+
`this._navigation.next()` to get this protection (also in 18.3.15).
|
|
279
|
+
- `captcha`: no more `NG0953` warning ("Unexpected emit for destroyed `OutputRef`") when the captcha script fails to
|
|
280
|
+
load after the component has been destroyed (e.g. the user left the page meanwhile).
|
|
281
|
+
- `foehn-multiselect-autocomplete`: the suggestions and the message displayed once every element is selected follow a
|
|
282
|
+
model changed by the project, not only by the user. Once every element was selected, a model set back to some of
|
|
283
|
+
them kept the message and the hidden input; a model selecting every element did not display the message; the
|
|
284
|
+
suggestions still contained the elements selected by the project. An empty list of elements no longer displays
|
|
285
|
+
the message (every element of the list has already been added).
|
|
286
|
+
- `providePrestationsNgCore()` registers again the HTTP interceptors lost with `FoehnPageModule` in 19.0.0: the
|
|
287
|
+
`foehn-transmit-waiting-modal` is displayed again during a long transmission, the warning before the expiration of
|
|
288
|
+
the session receives its date again, and a new version of the application deployed meanwhile is detected again.
|
|
289
|
+
- `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes:
|
|
290
|
+
- the model is no longer set back to its previous value when the parent changes `elements` and `model`
|
|
291
|
+
at the same time
|
|
292
|
+
- no more error when the component is destroyed while its `elementsUrl` is loading
|
|
293
|
+
- with a `defaultElementValue`, the model can be emptied again (e.g. set to `null` by the parent): the
|
|
294
|
+
default value was set back at once
|
|
295
|
+
- a change of the model or of `disabled` no longer processes the elements again (the default value, the
|
|
296
|
+
display of the model, the grouped elements and, for the autocompletes, the matching of the model)
|
|
297
|
+
- `foehn-autocomplete`:
|
|
298
|
+
- the model is subscribed only once, whatever the number of times the elements are retrieved: the value
|
|
299
|
+
to display was selected again for each retrieval
|
|
300
|
+
- the height of the suggestion list always follows `itemHeightInSuggestionListInPx`, even before the first
|
|
301
|
+
search returning less than 5 suggestions
|
|
302
|
+
- dynamic list (`isSuggestionListDynamic`): a model already set is no longer reset, even for a moment
|
|
303
|
+
(`modelChange` emitted `null`, then the value again), when the loaded elements do not contain it; it is
|
|
304
|
+
displayed once the elements loaded for it contain it, including when they are given at once with the model
|
|
305
|
+
- `isSuggestionListDynamic` can change at runtime: only the matching of the current kind of list is active,
|
|
306
|
+
the matching of the previous kind went on
|
|
307
|
+
- dynamic list: a model changed by the project (another value, `null`) is displayed again; once a value had been
|
|
308
|
+
displayed, the display no longer followed the model. The elements loaded for the search of the user still do
|
|
309
|
+
not replace what they type.
|
|
310
|
+
- `foehn-input-address` without zone.js: an address given by the parent right after the initialization of the
|
|
311
|
+
component (e.g. prefilled with `SessionInfoWithApplicationService.prefillForm()` for a connected user) is no
|
|
312
|
+
longer overwritten by the model with the default country only; the default country and the clean-up of the model
|
|
313
|
+
are applied after the next rendering, from the latest model.
|
|
314
|
+
- `foehn-input-address` in Switzerland only (`isOnlySwiss`): an address given by the page without country after the
|
|
315
|
+
initialization of the component (e.g. a form loaded from the backend) gets the Swiss country again, as in v18: it
|
|
316
|
+
kept `country: null` until the user changed a field. The default country is checked again for every model given by
|
|
317
|
+
the page, and written only when it changes the model: an identical model is no longer written back (one
|
|
318
|
+
`modelChange` less), and an address without any value to display is left as it is.
|
|
319
|
+
- `foehn-input-address`: the streets and the street numbers of an address given by the page are loaded again, as in
|
|
320
|
+
v18. Since 19.0.0, they were only loaded once the user chose a locality and a street (the autocompletes no longer
|
|
321
|
+
emit `modelChange` for a model given by the page), and a locality given with its `zipCodeId` only (without
|
|
322
|
+
`postalLocalityHistoryId`) never loaded its streets. The lists now follow the locality and the street, whether
|
|
323
|
+
they come from the page or from the user. The Swiss localities are requested once the Swiss fields are displayed,
|
|
324
|
+
and again only when their URL changes (`swissNpaLocalityBaseUrl`, `specifiedCanton`, `withCompanyLocalities`), no
|
|
325
|
+
longer each time Switzerland is chosen again. The methods `userInputCountry()`, `userInputLocality()` and
|
|
326
|
+
`userInputStreet()` no longer take a parameter.
|
|
327
|
+
- `foehn-input-address`: the deferred clean-up of the model (hidden address lines and post office box) applies
|
|
328
|
+
to the latest model, it could restore a previous value (e.g. remove the default country); nothing is
|
|
329
|
+
updated anymore once the component is destroyed.
|
|
330
|
+
- `FoehnInputComponent`: when the user empties at once every field of a model given by the page, the model is `null`
|
|
331
|
+
again, as in v18, for the components overriding `onModelChange()` without calling `super.onModelChange()`: in
|
|
332
|
+
prestations-ng `foehn-input-date`, `foehn-input-date-time`, `foehn-input-foreign-locality` and
|
|
333
|
+
`foehn-input-foreign-street` (also in the foreign address of `foehn-input-address`), and in your project e.g. a
|
|
334
|
+
list whose last item is removed. Since 19.0.0, the model kept its previous value, which was then saved. The model
|
|
335
|
+
of the page is now known (`model_`) once it has a value to display, and then follows it, before `onModelChange()`,
|
|
336
|
+
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
|
|
337
|
+
display (e.g. an id) and which updates its model without any input of the user: override the new protected method
|
|
338
|
+
`hasValueToDisplay()`, as `foehn-input-address` does for the country of an address only Swiss.
|
|
339
|
+
- `foehn-input-date-time`: emptying its only filled field empties the model, it kept its value also in v18.
|
|
340
|
+
- `foehn-input-hidden`, `foehn-input-email` and `foehn-input-password` handle their model as `foehn-input-text` does:
|
|
341
|
+
a number `0` given by the page (e.g. a number field in Java bound to a `foehn-input-hidden`) is kept, it was
|
|
342
|
+
replaced by `null`, which was then saved. An empty string is replaced by `null` at once, instead of after a timer
|
|
343
|
+
that `fixture.whenStable()` didn't wait for, and that could overwrite a value given by the page meanwhile. Their
|
|
344
|
+
public field `timeoutReference` is removed.
|
|
345
|
+
- `foehn-input-textarea` replaces by `null` an empty string given by the page, as the other text fields do. Its
|
|
346
|
+
character count follows a change of `max` or `displayCharCount` at once: it kept the previous count until the next
|
|
347
|
+
input, and the textarea stayed `aria-invalid` once the count was no longer displayed.
|
|
348
|
+
- `foehn-radio`: `inputValue` follows a change of `elementValue` or `elementValueIdentity`, not only of the model.
|
|
349
|
+
- `foehn-input-time` replaces by `null` an empty string given by the page, as the other text fields do: the backend
|
|
350
|
+
rejected it (`@ValidStringTime` accepts `null`, not `''`), although the user had entered nothing.
|
|
351
|
+
- 🚨 `ObjectHelper.hasAnyValue()` and `ObjectHelper.isEmpty()`: a number (`0` included), a boolean (`false`
|
|
352
|
+
included) and a date are values. `true`, `5` or a date were empty, as well as `0`, `false` or a date in an object
|
|
353
|
+
or an array (e.g. `{ checked: false }`, `[0, 0]`). Only `null`, `undefined`, `''` and the arrays and objects
|
|
354
|
+
holding none but them are empty. Check your calls on such values, e.g. in the `getValidValue()` of your
|
|
355
|
+
components: a field holding `true` no longer counts as empty.
|
|
356
|
+
- `foehn-multi-upload` and `foehn-bo-multi-upload`:
|
|
357
|
+
- after a failed upload (network, HTTP error), the next files are uploaded: nothing was uploaded anymore,
|
|
358
|
+
without any message, until the page was reloaded
|
|
359
|
+
- after a failed deletion (HTTP error, readonly document), the next files are deleted: nothing was deleted
|
|
360
|
+
anymore, and the error also reached the `ErrorHandler` as unhandled (its message is still displayed)
|
|
361
|
+
- `PendingUploadService.removePendingFile()`: a file which is not pending no longer removes the last pending file.
|
|
362
|
+
- `foehn-multi-upload` and `foehn-bo-multi-upload`: `customErrors` is used again for the errors which have a default
|
|
363
|
+
message (`413`, `415`, `500`, `FILENAME_TOO_LONG`, `FILENAME_SHOULD_NOT_CONTAIN`...): the default messages
|
|
364
|
+
overwrote the given object. Its messages can use `{fileName}` and `{fileMaxSize}`, `{fileExtensions}`,
|
|
365
|
+
`{maxFileNameLength}`, `{fileNameIllegalCharacters}` (as documented) as well as `%1$s` and `%2$s`.
|
|
366
|
+
- `UploaderHelper`: `getDefaultCustomErrors()` and `mergeCustomErrors()` are added, `createDefaultCustomErrors()` is
|
|
367
|
+
deprecated as it overwrites the given custom errors.
|
|
368
|
+
- `foehn-agenda-timeslot-panel`: when the time slots of the day change, the panel is closed again (only the
|
|
369
|
+
first time slots are displayed) unless the selected slot would be hidden; the list was cut while the panel
|
|
370
|
+
stayed open.
|
|
371
|
+
- `foehn-breadcrumb`: a breadcrumb updated in place is displayed again when it is emitted.
|
|
372
|
+
- `fromDictionary` pipe: its subscription is released when the pipe is destroyed.
|
|
373
|
+
- `SdkLogsService`: a log is not sent anymore once the application is destroyed (e.g. at the end of a test),
|
|
374
|
+
when it made the `HttpClient` throw `NG0205`.
|
|
375
|
+
- `SessionInfoWithApplicationService`: `isReady` and `isUserConnected` return the same `Observable` at each read. A
|
|
376
|
+
new one at each read made the `async` pipe of a template subscribe again at each refresh: on a resumed application
|
|
377
|
+
whose form is loaded before the session, `isReady` went back to `null` and hid the content until the session
|
|
378
|
+
arrived.
|
|
379
|
+
- `foehn-list-summary` with `showAsTable`: the table displays the list given by the page when the page replaces it
|
|
380
|
+
(e.g. with the form returned by the backend). Since 19.0.0, it only followed the removals and the sorts made in
|
|
381
|
+
the component.
|
|
382
|
+
- `ng add @dsivd/prestations-ng` works again on the Angular workspaces created since Angular 14: it failed because
|
|
383
|
+
`angular.json` no longer has a `defaultProject` (the dependencies are now added to every application), then
|
|
384
|
+
because of the comments of `tsconfig.json` (now kept, like its formatting).
|
|
385
|
+
- `foehn-feedback-notification`: an error of `api/feedbacknotification/queryparams/{reference}` is logged and the
|
|
386
|
+
links are displayed without the feedback url, it reached the `ErrorHandler` as unhandled.
|
|
387
|
+
- The npm package no longer contains its own archive (`dsivd-prestations-ng-<version>.tgz`).
|
|
388
|
+
- ESLint rules [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) and
|
|
389
|
+
[`no-uninvoked-signal-in-template`](ESLINT_PLUGIN.md#no-uninvoked-signal-in-template): an explicit `(xChange)`
|
|
390
|
+
handler is no longer taken for the target of a two-way binding `[(x)]`. `no-direct-signal-mutation` reported
|
|
391
|
+
`(modelChange)="updateModel()"` in a template shared by several components (its component file not found), and
|
|
392
|
+
`no-uninvoked-signal-in-template` let `(valueChange)="mySignal"` through.
|
|
393
|
+
|
|
16
394
|
## [19.1.1]
|
|
17
395
|
|
|
18
396
|
### Fixed
|
|
@@ -155,6 +533,24 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
155
533
|
- [foehn-list-summary.component.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-summary.component.ts)
|
|
156
534
|
- `[list]` attribut has been removed. Use `[model]` instead.
|
|
157
535
|
|
|
536
|
+
## [18.3.15]
|
|
537
|
+
|
|
538
|
+
### Updated
|
|
539
|
+
|
|
540
|
+
- [foehn-navigation.component.html](projects/prestations-ng/src/foehn-navigation/foehn-navigation/foehn-navigation.component.html)
|
|
541
|
+
- [foehn-simple-navigation.component.html](projects/prestations-ng/src/foehn-navigation/foehn-simple-navigation/foehn-simple-navigation.component.html)
|
|
542
|
+
- while the page targeted by "next", "transmit" or "previous" is loading for more than 200 ms (e.g. lazy loaded route), the clicked button displays a spinner with the new `loadingLabel` input (dictionary key `foehn-navigation.loading.label`, "Chargement...") and the navigation buttons are disabled (`aria-disabled`; clicks are ignored from the start of the navigation); a `role="status"` region announces the loading to screen readers
|
|
543
|
+
- [foehn-navigation.service.ts](projects/prestations-ng/src/foehn-navigation/foehn-navigation.service.ts)
|
|
544
|
+
- new method `pendingNavigationDirection()`: direction of the navigation started with `next()` or `previous()` until it ends, `null` otherwise
|
|
545
|
+
|
|
546
|
+
### Fixed
|
|
547
|
+
|
|
548
|
+
- [abstract-page-component.ts](projects/prestations-ng/src/abstract-page-component.ts)
|
|
549
|
+
- fixed a second click on "next" or "transmit" while the next page is loading (lazy loaded route, resolver, async guard) saving again and skipping the next page: `send()`, `sendAndTransmit()` and `transmit()` are now ignored until the navigation to the next page ends
|
|
550
|
+
- new protected method `navigateToNextPage()`: pages overriding `onFormSent()` should call it instead of `this._navigation.next()` to get this protection
|
|
551
|
+
- [abstract-page-from-menu.component.ts](projects/prestations-ng/src/foehn-menu-prestation/abstract-page-from-menu.component.ts)
|
|
552
|
+
- same fix when returning to the parent page
|
|
553
|
+
|
|
158
554
|
## [18.3.13]
|
|
159
555
|
|
|
160
556
|
### Fixed
|
package/CONTRIBUTING.md
CHANGED
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
- Node 22.18+
|
|
6
6
|
- npm 10.2+
|
|
7
|
-
- Chrome or Chromium
|
|
8
7
|
- G++
|
|
9
8
|
|
|
9
|
+
Chromium is downloaded by Puppeteer during `npm install`: it is used by the unit tests (through Playwright)
|
|
10
|
+
and by the e2e tests (Cypress).
|
|
11
|
+
|
|
10
12
|
## Developing using the Dev Tool
|
|
11
13
|
|
|
12
14
|
Since version `8`, `prestations-ng` has a standalone application that allows
|
|
@@ -92,9 +94,10 @@ This project uses a set of scripts to lint and format the code, along with pre-c
|
|
|
92
94
|
|
|
93
95
|
Important scripts are :
|
|
94
96
|
|
|
95
|
-
- `npm run lint` : run ESLint and Prettier on all files
|
|
97
|
+
- `npm run lint` : run ESLint and Prettier on all files, and check the types of the TypeScript files compiled by no
|
|
98
|
+
build (`lint:types`: `cypress/`, which Cypress only transpiles, and the configuration files of `tsconfig.config.json`)
|
|
96
99
|
- `npm run format`: run ESLint and Prettier on all files and fix errors automatically
|
|
97
|
-
- `npm run validate`: clean and run all tests
|
|
100
|
+
- `npm run validate`: clean, lint and run all tests
|
|
98
101
|
|
|
99
102
|
**Husky** is used as a pre-commit hook to automatically output linting and formatting errors for staged files before committing.
|
|
100
103
|
In the end, this utilitary calls `npm run lint-staged` which you can also call yourself of course. To have this pre-commit hook,
|
|
@@ -168,7 +171,7 @@ Alternatively, you can manually publish the package. Although this method is not
|
|
|
168
171
|
- Ensure you can push to the npm registry: `npm adduser --registry=https://registry.npmjs.org --scope=@dsivd`
|
|
169
172
|
- Update the version number in `package.json` either manually or with `npm version`
|
|
170
173
|
- Commit and tag the version change
|
|
171
|
-
- Package a new version of the library with `npm package`
|
|
174
|
+
- Package a new version of the library with `npm run package`
|
|
172
175
|
- Publish the package:
|
|
173
176
|
- `npm run publish:stable` for stable version (released to everybody)
|
|
174
177
|
- `npm run publish:next` for next version (development only)
|
|
@@ -218,6 +221,73 @@ export NODE_OPTIONS=--max_old_space_size=4096
|
|
|
218
221
|
|
|
219
222
|
Use at your own risks.
|
|
220
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 plain fields that the pages of the projects set
|
|
240
|
+
when their form is loaded: `AbstractPageComponent` marks the page then).
|
|
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
|
+
|
|
252
|
+
## Unit testing
|
|
253
|
+
|
|
254
|
+
The unit tests run with [Vitest](https://vitest.dev/) through the `@angular/build:unit-test` builder of the
|
|
255
|
+
Angular CLI, in the browser mode of Vitest: [Playwright](https://playwright.dev/) drives the headless Chromium
|
|
256
|
+
downloaded by Puppeteer (another browser can be used by setting the `CHROME_BIN` environment variable).
|
|
257
|
+
Neither the library nor the Dev Tool uses zone.js: the tests are **zoneless** too.
|
|
258
|
+
|
|
259
|
+
| Command | Tests |
|
|
260
|
+
| ------------------------- | ---------------------------------------------------------------- |
|
|
261
|
+
| `npm run test:lib` | library (`projects/prestations-ng/src/**/*.spec.ts`) |
|
|
262
|
+
| `npm run test:devtool` | Dev Tool (`src/**/*.spec.ts`) |
|
|
263
|
+
| `npm run test:schematics` | schematics, in Node.js (`projects/prestations-ng/schematics`) |
|
|
264
|
+
| `npm run test:eslint` | ESLint plugin, in Node.js (`projects/prestations-ng/src/eslint`) |
|
|
265
|
+
| `npm test` | builds the library, then runs all of the above |
|
|
266
|
+
|
|
267
|
+
- `ng test prestations-ng` without `--no-watch` runs the tests in watch mode.
|
|
268
|
+
- Only some specs: `ng test prestations-ng --no-watch --include=foehn-table` (folder or file, relative to
|
|
269
|
+
`projects/prestations-ng/src`), and `--filter="FoehnTableComponent"` to filter by test name.
|
|
270
|
+
- The configuration is in `angular.json` (`test` targets), in the `vitest-base.config.mts` file of each project and in
|
|
271
|
+
the `vitest-base.config.mts` file they share, at the root.
|
|
272
|
+
The coverage of the library is written in `projects/prestations-ng/coverage` (read by SonarQube).
|
|
273
|
+
- The configuration files of the tools (`.mjs`/`.mts`, e.g. `eslint.config.mjs`, `vitest-base.config.*`) are listed in
|
|
274
|
+
`tsconfig.config.json`, referenced by `tsconfig.json`: the IDE checks them with the options of the project instead of
|
|
275
|
+
its default ones. Add any new configuration file to its `files`.
|
|
276
|
+
|
|
277
|
+
### Writing zoneless tests
|
|
278
|
+
|
|
279
|
+
- Use `vi` (`vi.spyOn()`, `vi.fn()`...), the Jest-like API of Vitest. Unlike `spyOn()` in Jasmine,
|
|
280
|
+
`vi.spyOn()` calls the original method: add `.mockReturnValue(...)` or `.mockImplementation(...)` to stub it.
|
|
281
|
+
The spies are restored before each test.
|
|
282
|
+
- `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` require zone.js: use `async` tests with
|
|
283
|
+
`await fixture.whenStable()`, or `vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)`.
|
|
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()`.
|
|
288
|
+
- Without zone.js, `fixture.detectChanges()` only refreshes the views that have been notified. A test (or a test
|
|
289
|
+
host component) changing the state of a component must use signals, as the components do.
|
|
290
|
+
|
|
221
291
|
## E2E testing
|
|
222
292
|
|
|
223
293
|
`Protractor` is no longer included in new Angular projects as of Angular 12.
|