@dsivd/prestations-ng 19.1.2 → 19.2.0-beta.10

package/CHANGELOG.md

@@ -6,15 +6,194 @@
 
 ---
 
-## [19.1.2]
+## [19.2.0] - should be aligned with prestations-be 19.2.x
 
-### Fixed
+### Added
+
+- [eslint/configs/spec-ts-recommended.mjs](projects/prestations-ng/src/eslint/configs/spec-ts-recommended.mjs)
+    - New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
+      `**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
+      the `HttpTestingController` and of the helpers of the specs. It needs `@vitest/eslint-plugin` in the
+      devDependencies of your project, only when you use it. See
+      [UPGRADING_V19.md](UPGRADING_V19.md#migrate-to-eslint-flat-configuration).
+- [foehn-bo-multi-upload.component.ts](projects/prestations-ng/src/foehn-upload/foehn-bo-multi-upload/foehn-bo-multi-upload.component.ts)
+    - New `localUpload` input. When set to `true`, selected files are kept purely local
+      (as `DocumentReferenceWithFile`, no `uploadUrl()` call) so they can be cancelled before
+      being sent. Files show up immediately in the list with a "pending" indicator (dictionary
+      key `foehn-uploader.pending-label`, French default provided) since they're not uploaded
+      yet. It is your responsibility to upload/delete them at save time,
+      e.g. via the new
+      [document-changes.helper.ts](projects/prestations-ng/src/foehn-upload/document-changes.helper.ts)
+      (`splitDocumentChanges`) which computes `filesToAdd`/`documentsToDelete` from the model.
+    - The default (direct upload) mode is unchanged.
+    - New `maxFileSizeInMo` input: a client-side, per-file size limit that doesn't depend on
+      the `fileMaxSizeInBytesByFormKey` server configuration (useful for consumers that don't
+      expose that config yet). When both are set, the smallest limit applies. A file too big gets
+      the usual `413` error, which can be customized with `customErrors` (`{fileName}`,
+      `{fileMaxSize}`).
+    - New `chooseButtonStyleModifier` input, appended to the choose button's CSS classes
+      (e.g. `btn-sm`), mirroring the same input already available on other uploaders.
+
+- [foehn-input-address.component.ts](projects/prestations-ng/src/foehn-address/foehn-input-address.component.ts)
+    - Added `streetAllowCustomValue` input to control whether the street field allows custom values (defaults to `true`).
+    - Added `swissNpaLocalityBaseUrl` input to control the base URL for Swiss NPA localities (defaults to `'api/refinf/locality'`).
+
+### Changed
+
+Library now runs as strict mode, which may cause some errors to appear in your project after updating.
+Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information.
+
+- [foehn-list-summary.component.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-summary.component.ts)
+    - `FoehnListSummaryComponent` is now generic: `FoehnListSummaryComponent<T extends FoehnListItem>`,
+      so the model, `getListItemTitle` and `listItemDescriptions` are typed with your own item class
+      instead of the base `FoehnListItem`
+- [foehn-list-item-description.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-item-description.ts)
+    - 🚨 `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
+      `getFormattedValue(item: T)` and `hideIfEmpty(item: T)` receive your item type directly, no cast needed.
+      Replace `FoehnListItemDescription[]` with `FoehnListItemDescription<MyItem>[]` in your project.
+- [uploader.helper.ts](projects/prestations-ng/src/foehn-upload/uploader.helper.ts)
+    - 🚨 `UploaderHelper.addCustomErrorOrDefault()` takes the limits of the uploader in an object (`UploaderErrorLimits`,
+      all optional) instead of its last three parameters:
+      `addCustomErrorOrDefault(name, errors, errorCode, fileName, customErrors, { overrideAcceptedExtensions, overrideMaxFileNameLength, overrideIllegalCharacters, maxFileSizeInMo })`.
+      The custom error 413 returned by the server now also displays the `maxFileSizeInMo` limit of
+      `foehn-bo-multi-upload`.
+- 🚀 **prestations-ng is now zoneless**: its components no longer need zone.js to be refreshed. They keep
+  working in an application using zone.js, and your application can now drop zone.js, see
+  [UPGRADING_V19.md](UPGRADING_V19.md#zoneless-optional-but-recommended).
+    - the state displayed by the components is held by signals (`signal()`, `computed()`, `linkedSignal()`)
+    - what was waiting for `NgZone.onMicrotaskEmpty` or a `setTimeout()` to reach the rendered DOM (focus,
+      scroll, value displayed by the autocompletes, default values...) now uses `afterNextRender()`
+    - the short asynchronous work of the components is tracked with `PendingTasks`, so that
+      `ApplicationRef.whenStable()` (and `fixture.whenStable()` in your tests) waits for it: the debounced
+      `userInput` output of the `foehn-input-*` components, the debounced time of `foehn-input-date-time`,
+      the locale of `foehn-date-picker`, the default country and the sanitized model of `foehn-input-address`
+    - `providePrestationsNgCore()` now provides `provideBrowserGlobalErrorListeners()`: without zone.js, the
+      errors thrown in a timer or a promise still reach your `ErrorHandler`
+- 🚨 **The inputs and outputs of the components are unchanged**, but the following public fields are now
+  signals. If your code reads them (e.g. through `viewChild()` or in your tests), call them (`isVisible()`
+  instead of `isVisible`) and write them with `.set()`. Those marked _read-only_ are `computed()` signals.
+    - `foehn-agenda`: `srAnnouncements`
+    - `foehn-agenda-timeslot-panel`: `selectedTimeSlot`, `timeInputValue`, `isClosed`, `timeSlots`
+      (_read-only_), `timeslotRemaining` (_read-only_), `canClose` (_read-only_)
+    - `foehn-autocomplete`: `searchValue`, `inputHasFocus`, `hideSuggestions`, `displayedElements`,
+      `notificationMessageUpdated`, `VIEW_PORT_HEIGHT` (_read-only_)
+    - `foehn-multiselect-autocomplete`: `autocompleteInputValue`, `showEmptyListMessage` (_read-only_), `srAnnouncements`
+    - `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes (`FoehnCheckableGroupComponent`):
+      `groupedElements`
+    - `foehn-radio`: `inputValue`
+    - `foehn-confirm-modal`: `isVisible` (`content` is now a read-only field instead of a getter)
+    - `foehn-date-picker`: `hostId`, `weekDays`, `weeks`, `selectedDate`, `monthListItem`
+    - `foehn-dropdown-menu`: `isDropdownVisible`, `popupPosition`
+    - `foehn-header`: `connectedEsMenu` (_read-only_)
+    - `foehn-input-address`: `country`, `locality`, `street`, `houseNumber`, `postOfficeBoxText`,
+      `addressLine1`, `addressLine2` (linked to the model: they follow it and can still be set),
+      `streetCustomErrors`
+    - `foehn-input-foreign-locality`: `zipCode`, `longName`
+    - `foehn-input-foreign-street`: `longName`
+    - `foehn-input-date`: `day`, `month`, `year`, `datePickerModel`
+    - `foehn-input-date-time`: `date`, `time` (linked to the model: they follow it and can still be set)
+    - `foehn-input-time`: `hour`, `minute` (linked to the model: they follow it and can still be set)
+    - `foehn-input-nav13`: `part2`, `part3`, `part4`
+    - `foehn-input-textarea`: `isCharCountExceeded`, `charCountLeft`, `charCountLabel`, `ariaLiveStatus`
+    - `foehn-list` and `foehn-table`: `currentPage`, `filteredList`
+    - `foehn-list-summary`: `listCopyForTable`, `tableConfiguration` (_read-only_)
+    - `foehn-notfound`: `seconds`
+    - `foehn-page`: `pageTitle`
+    - `foehn-page-counter`: `isStable` (was an `Observable<boolean>`)
+    - `foehn-page-modal`: `wrongPublicModalVisible`, `formattedPublicsCibles`
+    - `foehn-picture-upload`: `pictureToCrop`, `croppedPictureAsBlob`, `loading`
+    - `foehn-status-progress-bar`: `isTransmitted`
+    - `gesdem-action-recovery-login`: `demandeNotFound`, `rateLimited`, `rateLimitCounter`, `otpRecipient`,
+      `otp`
+    - `gesdem-action-recovery-registration`: `mailSent`, `model` (replaced by the new `updateModel()` method,
+      never mutated)
+    - `epayment-form` (`SdkEpaymentComponent`): `failureModalDisplayed`, `redirectModalDisplayed`
+    - `captcha` (`SdkRecaptchaComponent`): `isLoaded`, `hasLoadingError`
+    - `redirector` (`RedirectComponent`): `counter`
+- The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
+  `foehn-agenda-timeslot-panel`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` and `ngOnDestroy()`
+  of `captcha`.
+- `SdkDictionaryService.getKeySync()` reads a signal: a `computed()` or a template calling it is refreshed
+  when the dictionary is (re)loaded, e.g. when the language changes.
+- `foehn-autocomplete` and `foehn-multiselect-autocomplete`: the value to display, its reset, the default
+  values and the focus after a click on a suggestion are applied after the next rendering instead of in a
+  `setTimeout()`.
+- Unit tests of the library: Karma and Jasmine are replaced by Vitest 4 in browser mode (Playwright,
+  headless Chromium), see [CONTRIBUTING.md](CONTRIBUTING.md#unit-testing).
+- `core-js` is no longer a peer dependency: prestations-ng no longer imports it since 19.1.1, see
+  [UPGRADING_V19.md](UPGRADING_V19.md#core-js-is-no-longer-needed-since-1920).
+- `ng add @dsivd/prestations-ng` adds `iban` and `dayjs` (the CommonJS dependencies of prestations-ng) to the
+  `allowedCommonJsDependencies` of `angular.json`, instead of `core-js/modules/es.array.includes`, `iban` and
+  `zone.js/dist/zone-error`, and no longer sets `allowSyntheticDefaultImports` (implied by the `tsconfig.json` of
+  Angular 21: `"module": "preserve"` or `"moduleResolution": "bundler"`).
+
+### Deprecated
 
-- [provide-prestations-ng-core.ts](projects/prestations-ng/src/provide-prestations-ng-core.ts)
-    - `providePrestationsNgCore()` registers again the HTTP interceptors lost with `FoehnPageModule` in 19.0.0:
-      the `foehn-transmit-waiting-modal` is displayed again during a long transmission, the warning before the
-      expiration of the session receives its date again, and a new version of the application deployed meanwhile is
-      detected again.
+- `AbstractMenuPageComponent.ngZone` is no longer used and will be removed: `NgZone.onStable` never emits
+  without zone.js.
+
+### Fixed
+
+- `captcha`: no more `NG0953` warning ("Unexpected emit for destroyed `OutputRef`") when the captcha script fails to
+  load after the component has been destroyed (e.g. the user left the page meanwhile).
+- `foehn-multiselect-autocomplete`: the suggestions and the message displayed once every element is selected follow a
+  model changed by the project, not only by the user. Once every element was selected, a model set back to some of
+  them kept the message and the hidden input; a model selecting every element did not display the message; the
+  suggestions still contained the elements selected by the project. An empty list of elements no longer displays
+  the message (every element of the list has already been added).
+- `providePrestationsNgCore()` registers again the HTTP interceptors lost with `FoehnPageModule` in 19.0.0: the
+  `foehn-transmit-waiting-modal` is displayed again during a long transmission, the warning before the expiration of
+  the session receives its date again, and a new version of the application deployed meanwhile is detected again.
+- `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes:
+    - the model is no longer set back to its previous value when the parent changes `elements` and `model`
+      at the same time
+    - no more error when the component is destroyed while its `elementsUrl` is loading
+    - with a `defaultElementValue`, the model can be emptied again (e.g. set to `null` by the parent): the
+      default value was set back at once
+    - a change of the model or of `disabled` no longer processes the elements again (the default value, the
+      display of the model, the grouped elements and, for the autocompletes, the matching of the model)
+- `foehn-autocomplete`:
+    - the model is subscribed only once, whatever the number of times the elements are retrieved: the value
+      to display was selected again for each retrieval
+    - the height of the suggestion list always follows `itemHeightInSuggestionListInPx`, even before the first
+      search returning less than 5 suggestions
+    - dynamic list (`isSuggestionListDynamic`): a model already set is no longer reset, even for a moment
+      (`modelChange` emitted `null`, then the value again), when the loaded elements do not contain it; it is
+      displayed once the elements loaded for it contain it, including when they are given at once with the model
+    - `isSuggestionListDynamic` can change at runtime: only the matching of the current kind of list is active,
+      the matching of the previous kind went on
+    - dynamic list: a model changed by the project (another value, `null`) is displayed again; once a value had been
+      displayed, the display no longer followed the model. The elements loaded for the search of the user still do
+      not replace what they type.
+- `foehn-input-address` without zone.js: an address given by the parent right after the initialization of the
+  component (e.g. prefilled with `SessionInfoWithApplicationService.prefillForm()` for a connected user) is no
+  longer overwritten by the model with the default country only; the default country and the clean-up of the model
+  are applied after the next rendering, from the latest model.
+- `foehn-input-address`: the deferred clean-up of the model (hidden address lines and post office box) applies
+  to the latest model, it could restore a previous value (e.g. remove the default country); nothing is
+  updated anymore once the component is destroyed.
+- `foehn-multi-upload` and `foehn-bo-multi-upload`:
+    - after a failed upload (network, HTTP error), the next files are uploaded: nothing was uploaded anymore,
+      without any message, until the page was reloaded
+    - after a failed deletion (HTTP error, readonly document), the next files are deleted: nothing was deleted
+      anymore, and the error also reached the `ErrorHandler` as unhandled (its message is still displayed)
+- `PendingUploadService.removePendingFile()`: a file which is not pending no longer removes the last pending file.
+- `foehn-multi-upload` and `foehn-bo-multi-upload`: `customErrors` is used again for the errors which have a default
+  message (`413`, `415`, `500`, `FILENAME_TOO_LONG`, `FILENAME_SHOULD_NOT_CONTAIN`...): the default messages
+  overwrote the given object. Its messages can use `{fileName}` and `{fileMaxSize}`, `{fileExtensions}`,
+  `{maxFileNameLength}`, `{fileNameIllegalCharacters}` (as documented) as well as `%1$s` and `%2$s`.
+- `UploaderHelper`: `getDefaultCustomErrors()` and `mergeCustomErrors()` are added, `createDefaultCustomErrors()` is
+  deprecated as it overwrites the given custom errors.
+- `foehn-agenda-timeslot-panel`: when the time slots of the day change, the panel is closed again (only the
+  first time slots are displayed) unless the selected slot would be hidden; the list was cut while the panel
+  stayed open.
+- `foehn-breadcrumb`: a breadcrumb updated in place is displayed again when it is emitted.
+- `fromDictionary` pipe: its subscription is released when the pipe is destroyed.
+- `SdkLogsService`: a log is not sent anymore once the application is destroyed (e.g. at the end of a test),
+  when it made the `HttpClient` throw `NG0205`.
+- `ng add @dsivd/prestations-ng` works again on the Angular workspaces created since Angular 14: it failed because
+  `angular.json` no longer has a `defaultProject` (the dependencies are now added to every application), then
+  because of the comments of `tsconfig.json` (now kept, like its formatting).
 
 ## [19.1.1]
 

package/CONTRIBUTING.md

@@ -4,9 +4,11 @@
 
 - Node 22.18+
 - npm 10.2+
-- Chrome or Chromium
 - G++
 
+Chromium is downloaded by Puppeteer during `npm install`: it is used by the unit tests (through Playwright)
+and by the e2e tests (Cypress).
+
 ## Developing using the Dev Tool
 
 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
 
 Important scripts are :
 
-- `npm run lint` : run ESLint and Prettier on all files
+- `npm run lint` : run ESLint and Prettier on all files, and check the types of the TypeScript files compiled by no
+  build (`lint:types`: `cypress/`, which Cypress only transpiles, and the configuration files of `tsconfig.config.json`)
 - `npm run format`: run ESLint and Prettier on all files and fix errors automatically
-- `npm run validate`: clean and run all tests
+- `npm run validate`: clean, lint and run all tests
 
 **Husky** is used as a pre-commit hook to automatically output linting and formatting errors for staged files before committing.
 In the end, this utilitary calls `npm run lint-staged` which you can also call yourself of course. To have this pre-commit hook,
@@ -218,6 +221,43 @@ export NODE_OPTIONS=--max_old_space_size=4096
 
 Use at your own risks.
 
+## Unit testing
+
+The unit tests run with [Vitest](https://vitest.dev/) through the `@angular/build:unit-test` builder of the
+Angular CLI, in the browser mode of Vitest: [Playwright](https://playwright.dev/) drives the headless Chromium
+downloaded by Puppeteer (another browser can be used by setting the `CHROME_BIN` environment variable).
+Neither the library nor the Dev Tool uses zone.js: the tests are **zoneless** too.
+
+| Command                   | Tests                                                            |
+| ------------------------- | ---------------------------------------------------------------- |
+| `npm run test:lib`        | library (`projects/prestations-ng/src/**/*.spec.ts`)             |
+| `npm run test:devtool`    | Dev Tool (`src/**/*.spec.ts`)                                    |
+| `npm run test:schematics` | schematics, in Node.js (`projects/prestations-ng/schematics`)    |
+| `npm run test:eslint`     | ESLint plugin, in Node.js (`projects/prestations-ng/src/eslint`) |
+| `npm test`                | builds the library, then runs all of the above                   |
+
+- `ng test prestations-ng` without `--no-watch` runs the tests in watch mode.
+- Only some specs: `ng test prestations-ng --no-watch --include=foehn-table` (folder or file, relative to
+  `projects/prestations-ng/src`), and `--filter="FoehnTableComponent"` to filter by test name.
+- The configuration is in `angular.json` (`test` targets), in the `vitest-base.config.mts` file of each project and in
+  the `vitest-base.config.mts` file they share, at the root.
+  The coverage of the library is written in `projects/prestations-ng/coverage` (read by SonarQube).
+- The configuration files of the tools (`.mjs`/`.mts`, e.g. `eslint.config.mjs`, `vitest-base.config.*`) are listed in
+  `tsconfig.config.json`, referenced by `tsconfig.json`: the IDE checks them with the options of the project instead of
+  its default ones. Add any new configuration file to its `files`.
+
+### Writing zoneless tests
+
+- Use `vi` (`vi.spyOn()`, `vi.fn()`...), the Jest-like API of Vitest. Unlike `spyOn()` in Jasmine,
+  `vi.spyOn()` calls the original method: add `.mockReturnValue(...)` or `.mockImplementation(...)` to stub it.
+  The spies are restored before each test.
+- `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` require zone.js: use `async` tests with
+  `await fixture.whenStable()`, or `vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)`.
+- `fixture.whenStable()` waits for the change detection and the Angular pending tasks (HTTP requests...), not
+  for the timers.
+- Without zone.js, `fixture.detectChanges()` only refreshes the views that have been notified. A test (or a test
+  host component) changing the state of a component must use signals, as the components do.
+
 ## E2E testing
 
 `Protractor` is no longer included in new Angular projects as of Angular 12.