@dsivd/prestations-ng 19.2.0-beta.27 → 19.2.0-beta.29

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.
Files changed (35) hide show
  1. package/AI_GUIDELINES.md +30 -9
  2. package/ANGULAR_SIGNALS.md +2 -2
  3. package/CHANGELOG.md +51 -3
  4. package/CONTRIBUTING.md +54 -12
  5. package/ESLINT_PLUGIN.md +110 -13
  6. package/GOOD_PRACTICES.md +34 -10
  7. package/README.md +18 -12
  8. package/UPGRADING_V19.md +154 -7
  9. package/eslint/configs/template-rules.mjs +3 -0
  10. package/eslint/rules/index.mjs +2 -0
  11. package/eslint/rules/no-direct-signal-mutation.mjs +104 -21
  12. package/eslint/rules/no-item-track-in-form-list.mjs +4 -3
  13. package/eslint/rules/require-track-index.mjs +162 -0
  14. package/eslint/signal-names.mjs +127 -21
  15. package/fesm2022/dsivd-prestations-ng.mjs +68 -22
  16. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  17. package/package.json +1 -1
  18. package/schematics/migration-collection.json +1 -1
  19. package/schematics/ng-update/migrations/update-19_2_0/index.js +15 -3
  20. package/schematics/utility/form-signal/class-migration.js +130 -6
  21. package/schematics/utility/form-signal/form-members.js +318 -0
  22. package/schematics/utility/form-signal/form-signal-migration.js +13 -75
  23. package/schematics/utility/form-signal/page-classes.js +11 -1
  24. package/schematics/utility/form-signal/template-migration.js +119 -10
  25. package/schematics/utility/never-connected-migration.js +87 -0
  26. package/schematics/utility/typescript-files.js +95 -0
  27. package/src/eslint/configs/template-rules.mjs +3 -0
  28. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +142 -0
  29. package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
  30. package/src/eslint/rules/index.mjs +2 -0
  31. package/src/eslint/rules/no-direct-signal-mutation.mjs +104 -21
  32. package/src/eslint/rules/no-item-track-in-form-list.mjs +4 -3
  33. package/src/eslint/rules/require-track-index.mjs +162 -0
  34. package/src/eslint/signal-names.mjs +127 -21
  35. package/types/dsivd-prestations-ng.d.ts +19 -3
package/AI_GUIDELINES.md CHANGED
@@ -2,7 +2,8 @@
2
2
 
3
3
  The rules an AI assistant follows in a project using `@dsivd/prestations-ng`. This file is published with the
4
4
  library and describes the version installed: import it into the instructions of your assistant rather than copying
5
- it, e.g. in the `.claude/CLAUDE.md` of your repository (the path is relative to the file holding the import):
5
+ it (see "Instructions for your AI assistant" in `UPGRADING_V19.md`), e.g. in the `.claude/CLAUDE.md` of your
6
+ project (the path is relative to the file holding the import):
6
7
 
7
8
  ```text
8
9
  @../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
@@ -23,6 +24,9 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
23
24
  new code, but the existing code works without them: change it only when asked (see "Zoneless" and "Strict mode" in
24
25
  `UPGRADING_V19.md`).
25
26
 
27
+ During a migration, follow the steps of `UPGRADING_V19.md` in order: these rules describe the code once migrated.
28
+ Don't apply one before the step of the guide that brings it, unless asked.
29
+
26
30
  ## The form of a page
27
31
 
28
32
  - `AbstractPageComponent` replaces the form with the JSON of the backend as is: at runtime, a field has the type of
@@ -32,11 +36,20 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
32
36
  `patchForm(path, value)` (a typed path, e.g. `['children', $index, 'firstName']`), the whole form with `form.set()`
33
37
  or `form.update()` and a new object. Never modify the form in place, and no `markForCheck()` after a write.
34
38
  - In the template, guard the fields with `@if (form(); as form)` inside `<foehn-form>`, which is never conditional
35
- itself. Bind a field with `[model]="form.x" (modelChange)="patchForm(['x'], $event)"`: never `[(model)]`, which
36
- modifies the form in place, and never `[model]` alone on a field the user can change (e.g. `foehn-list-summary`
37
- removes and sorts its items itself: without its `modelChange`, a removed item comes back once the form is saved).
38
- See "Binding the fields of the form" in `GOOD_PRACTICES.md`.
39
- - Track the rows of a list of the form by an identifier or `$index`, never by the item: `patchForm()` replaces it.
39
+ itself; the `@let form = this.form();` and `@if (form)` written by the migration are just as valid: keep them.
40
+ Bind a field with `[model]="form.x" (modelChange)="patchForm(['x'], $event)"`: never `[(model)]`, which modifies
41
+ the form in place, and never `[model]` alone on a field the user can change (e.g. `foehn-list-summary` removes and
42
+ sorts its items itself: without its `modelChange`, a removed item comes back once the form is saved). See "Binding
43
+ the fields of the form" in `GOOD_PRACTICES.md`.
44
+ - Track the rows of a `@for` by `$index`. The fields of a row are named with it, like the paths of the errors
45
+ (`[name]="'children[' + $index + '].firstName'"`): tracked by anything else, a row whose item moves (an item
46
+ removed before it, the list sorted) keeps these names, and the values and the errors of the rows get mixed up
47
+ (`require-track-index`). Only a list whose rows name nothing with the index and keep a state of their own (a
48
+ panel expanded, the focus, data loaded per item) while it can be reordered is tracked by an identifier of the item,
49
+ unique and stable. Never by the item itself when it is replaced (`patchForm()`, a new model), nor by a field the
50
+ row edits, nor by a `trackingIndex` kept by the project on its items (`FoehnListItem` has none). A page keeping the
51
+ errors of the server until its next save (a back office) renumbers them when it removes a row:
52
+ `ValidationHandlerService.removeListItemErrors('hearings[0].exchanges[1]')`, once per removal.
40
53
  Detail pages: `getListPath()`, `list()`, `itemToEdit()`, and `patchItem()`, `updateItem()` or `setItem()`.
41
54
  - The `modelChange` of a `foehn-*` component is emitted only when the component writes its model (an input of the
42
55
  user, a correction), never when the page changes it (form loaded, prefill, reset). React to the loaded form where
@@ -90,8 +103,12 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
90
103
  `(userInput)` handler, the variable of a `@for`), has side effects, is overridden or implements a contract.
91
104
  - Never modify in place a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new
92
105
  array or object.
93
- - An `Observable` displayed: `toSignal()` or the `async` pipe where it's displayed; the services keep returning
94
- `Observable`s. Never give the `async` pipe a method or a getter returning a new `Observable` at each read.
106
+ - Data read by a GET and displayed: `httpResource()` when the component builds the request, `rxResource()` over the
107
+ method of the service otherwise (Angular 21 has the API of Angular 22, where they are stable); read `value()` behind
108
+ `hasValue()`. It replaces a `subscribe()` setting the data and its loading or error flags by hand.
109
+ - Another `Observable` displayed: `toSignal()` or the `async` pipe where it's displayed; a `toSignal()` that works
110
+ stays. The services keep returning `Observable`s. Never give the `async` pipe a method or a getter returning a new
111
+ `Observable` at each read.
95
112
  - _Zoneless:_ a state read by a template and written by the code is a `signal()`, whoever writes it (a
96
113
  `subscribe()`, a promise, a timer, a hook, a method called by a listener). Act on the rendered DOM (focus, scroll)
97
114
  with `afterNextRender(..., { injector })`, never with `setTimeout()` or `NgZone`. `markForCheck()` only for a state
@@ -108,7 +125,8 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
108
125
  - Remove a method override only calling the parent method with the same arguments, and a constructor only calling
109
126
  `super()` (reported by `@typescript-eslint/no-useless-constructor`; see "A constructor only calling `super()`" in
110
127
  `ESLINT_PLUGIN.md` for a parent with a `protected` constructor). Remove an `inject()` field or an `input()` read
111
- neither by its class nor by its template: no tool reports an unused `protected` or public member.
128
+ neither by its class, nor by a subclass, nor by their templates: no tool reports an unused `protected` or public
129
+ member.
112
130
  - The rules of the ESLint plugin of the library (`no-direct-signal-mutation`, `require-model-change`,
113
131
  `no-item-track-in-form-list`...) report the mistakes above: fix the code, don't turn them off.
114
132
 
@@ -120,3 +138,6 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
120
138
  `HttpTestingController`, then `await fixture.whenStable()`; with Vitest, `vi.useFakeTimers()` and
121
139
  `await vi.advanceTimersByTimeAsync(ms)` for the timers. A test changing the state of a component uses signals, as
122
140
  the components do. See "Testing a zoneless component" in `GOOD_PRACTICES.md`.
141
+ - A loading resource keeps `whenStable()` waiting for its response: start its request with a first change detection
142
+ (`TestBed.tick()`; with zone.js `fixture.detectChanges()`, `TestBed.tick()` throwing NG0101 there), answer it with
143
+ `HttpTestingController`, then `await fixture.whenStable()`.
@@ -883,12 +883,12 @@ two-way expression.
883
883
 
884
884
  ```html
885
885
  <!-- 🔴 Tries to write through model()[i] — mutates in place, breaks reactivity -->
886
- @for (item of model(); track item.id; let i = $index) {
886
+ @for (item of model(); track $index; let i = $index) {
887
887
  <app-address-row [(model)]="model()[i]" />
888
888
  }
889
889
 
890
890
  <!-- đŸŸĸ One-way in, explicit handler out -->
891
- @for (item of model(); track item.id; let i = $index) {
891
+ @for (item of model(); track $index; let i = $index) {
892
892
  <app-address-row [model]="model()[i]" (modelChange)="updateItem(i, $event)" />
893
893
  }
894
894
  ```
package/CHANGELOG.md CHANGED
@@ -13,8 +13,10 @@
13
13
  - [AI_GUIDELINES.md](AI_GUIDELINES.md) (since 19.2.0-beta.27): the rules an AI assistant follows in a project using
14
14
  the library (the form of a page, the types of the fields, the components extending `FoehnInputComponent`, signals,
15
15
  TypeScript, tests), published with it for the version installed. The rules depending on the optional steps of the
16
- migration are marked _strict_ or _zoneless_. Import it into the instructions of your assistant, e.g.
17
- `@../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md` in the `.claude/CLAUDE.md` of your repository.
16
+ migration are marked _strict_ or _zoneless_. Import it into the instructions of your assistant as soon as the
17
+ library is installed, e.g. `@../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md` in the
18
+ `.claude/CLAUDE.md` of your project: see
19
+ [UPGRADING_V19.md](UPGRADING_V19.md#instructions-for-your-ai-assistant-since-1920).
18
20
 
19
21
  - [object-path.helper.ts](projects/prestations-ng/src/helpers/object-path.helper.ts)
20
22
  - New `ObjectPathHelper`: reads and writes a value at a path of any object, without modifying it: a write copies
@@ -37,7 +39,12 @@
37
39
  - `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
38
40
  classes and their templates (see the 🚨 entries below and
39
41
  [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
40
- migrate, and running it again changes nothing.
42
+ migrate, and running it again changes nothing. Since 19.2.0-beta.29, it also writes with `patchForm()` through a
43
+ getter of the page returning a path of the form (`this.step.motif = x`, `[(model)]="step.motif"` with
44
+ `get step() { return this.form.etape; }`, in the page or in a page it extends), and lists the writes through a
45
+ getter computing its value, the `effect()`s reading the form (directly or through a method: they run again at every
46
+ input of the user) and the methods writing the form called by the template outside an event (NG0600 while the view
47
+ is rendered).
41
48
  - 🚨 ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
42
49
  [`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
43
50
  `configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
@@ -45,6 +52,12 @@
45
52
  `(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
46
53
  at every input). Since 19.2.0-beta.22, `no-item-track-in-form-list` also reports the list held by the `model` of a
47
54
  component, and a row reading its item at its index (`[model]="model()[i]"`).
55
+ - 🚨 ESLint rule [`require-track-index`](ESLINT_PLUGIN.md#require-track-index) (since 19.2.0-beta.28), in
56
+ `configs.templateRules` and `configs.templateRecommended`: a `@for` whose rows name their fields (or the
57
+ `errorPrefix` of `foehn-error-pill`) with the index of the row must track them by `$index`. Tracked by an identifier,
58
+ a row whose item moves (an item removed before it, the list sorted) keeps the names of its former position:
59
+ `foehn-form` keeps its fields registered under them, and the values and the errors of the rows get mixed up. To turn
60
+ it off: `'@dsivd/prestations-ng/require-track-index': 'off'`.
48
61
 
49
62
  - [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
50
63
  - New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
@@ -101,6 +114,17 @@
101
114
  - [foehn-navigation.service.ts](projects/prestations-ng/src/foehn-navigation/foehn-navigation.service.ts)
102
115
  - new method `pendingNavigationDirection()`: direction of the navigation started with `next()` or `previous()`
103
116
  until it ends, `null` otherwise (also in 18.3.15)
117
+ - [form-error.helper.ts](projects/prestations-ng/src/validation/form-error.helper.ts) and
118
+ [validation-handler.service.ts](projects/prestations-ng/src/validation/validation-handler.service.ts) (since
119
+ 19.2.0-beta.29)
120
+ - new `FormErrorHelper.withoutListItem(errors, itemPath)`: the errors left once the item at `itemPath` (e.g.
121
+ `'hearings[0].exchanges[1]'`) is removed from its list, in a new array: its errors are dropped, and those of the
122
+ following items take the new index of their item, the items of their nested lists included
123
+ - new method `ValidationHandlerService.removeListItemErrors(itemPath)`: applies it to the errors given to
124
+ `updateErrors()` and publishes them. For a page keeping the errors of the server until its next save (e.g. a
125
+ back office) when it removes an item of a list whose fields are named with the index: the errors of the
126
+ following items would otherwise stay on their former index. No component of the library calls it. See
127
+ "Avoiding error display problems in a `@for` loop" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
104
128
 
105
129
  ### Changed
106
130
 
@@ -111,6 +135,14 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
111
135
  - `FoehnListSummaryComponent` is now generic: `FoehnListSummaryComponent<T extends FoehnListItem>`,
112
136
  so the model, `getListItemTitle` and `listItemDescriptions` are typed with your own item class
113
137
  instead of the base `FoehnListItem`
138
+ - The rows are tracked by their index (since 19.2.0-beta.28), as the prefix of their errors: sorted, a row no
139
+ longer keeps the errors of its former position. `trackFoehnListItem` returns the index, and the id of a row is
140
+ `list-summary-<its position from 1>` instead of `list-summary-<its trackingIndex>`.
141
+ - [foehn-list-item.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-item.ts)
142
+ - 🚨 `FoehnListItem.trackingIndex` is removed (since 19.2.0-beta.28): the library tracks the rows of a list by
143
+ their index (`require-track-index`). `AbstractListDetailPageComponent` no longer sets it on a new item, and its
144
+ `getNextTrackingIndex()` is removed. A project whose backend needs the field declares it in its item class and
145
+ sets it in `getNewListItem()` (see UPGRADING_V19.md).
114
146
  - [foehn-list-item-description.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-item-description.ts)
115
147
  - 🚨 `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
116
148
  `getFormattedValue(item: T)` and `hideIfEmpty(item: T)` receive your item type directly, no cast needed.
@@ -212,12 +244,22 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
212
244
  abstract `getList()`, which reads the list at that path. `list`, `itemIndex` and `itemToEdit` are now signals. The
213
245
  item edited is written with the new `patchItem(path, value)`, `updateItem(update)` (several fields in one write)
214
246
  and `setItem(item)`. A new item is added without modifying the list of the form in place.
247
+ - 🚨 `SessionInfo` reads the `NEVER_CONNECTED` token (since 19.2.0-beta.1): a provider
248
+ `{ provide: 'neverConnected', useValue: true }` is ignored without any error, and the application fetches the
249
+ session and displays the connected user or the login button. Provide `{ provide: NEVER_CONNECTED, useValue: true }`
250
+ instead. The `ng update` migration rewrites the providers, see
251
+ [UPGRADING_V19.md](UPGRADING_V19.md#neverconnected-is-provided-with-never_connected-since-1920).
215
252
  - `PendingUploadService` writes the documents uploaded with the form into a new form, instead of modifying the form
216
253
  in place.
217
254
  - 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) sees through the
218
255
  TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
219
256
  now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
220
257
  `[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
258
+ - 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#getters-handing-out-the-value) (since
259
+ 19.2.0-beta.29) follows the getters of the class returning the value of a signal or a part of it, through its
260
+ inheritance chain: `this.step.motif = value` and `[(model)]="step.motif"` with
261
+ `get step() { return this.form()!.etape; }` are now reported, as `this.form().count++` in TypeScript. Write the form
262
+ with `patchForm()`. To turn it off: `'@dsivd/prestations-ng/no-direct-signal-mutation': 'off'`.
221
263
  - The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
222
264
  `foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
223
265
  `foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
@@ -283,6 +325,12 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
283
325
 
284
326
  ### Fixed
285
327
 
328
+ - `foehn-checkbox` and `foehn-agenda` track their rows by their index (since 19.2.0-beta.28), as the names of their
329
+ fields: the checkboxes of elements reordered or replaced no longer share the control of the former ones.
330
+ - `foehn-agenda` follows its `disabled` input (since 19.2.0-beta.29), ignored until then: its time slots are disabled,
331
+ the navigation between the weeks stays usable. The time slot picked writes its model through `updateNgModel()`,
332
+ no longer with a two-way binding of its `model` (which bypassed the guard of a disabled component and the overrides
333
+ of `updateNgModel()`).
286
334
  - 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
287
335
  `elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
288
336
  autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
package/CONTRIBUTING.md CHANGED
@@ -6,7 +6,7 @@
6
6
  - npm 10.2+
7
7
  - G++
8
8
 
9
- Chromium is downloaded by Puppeteer during `npm install`: it is used by the unit tests (through Playwright)
9
+ Chromium is downloaded by Puppeteer during `npm ci`: it is used by the unit tests (through Playwright)
10
10
  and by the e2e tests (Cypress).
11
11
 
12
12
  ## Developing using the Dev Tool
@@ -20,11 +20,40 @@ in both the Dev Tool and the library reload the page.
20
20
 
21
21
  ### GitHub Pages documentation
22
22
 
23
- Official and beta documentation share the root `404.html` on GitHub Pages.
24
- Each documentation publication updates that fallback and adds URL restoration
25
- to both available app indexes, so deep links return to the correct app. Keep
26
- the fallback and restoration script in sync when changing the publishing flow.
27
- GitHub Pages still returns HTTP 404 for the initial deep-link request.
23
+ Each release publishes the Dev Tool on GitHub Pages, in the place given by the **NPM_TAG** of the Jenkins build and by
24
+ its version:
25
+
26
+ | Place | Release |
27
+ | --------------------------- | ----------------------------------------------------------------------------- |
28
+ | `/prestations-ng/` | STABLE, from master or from the release branch of the current minor version |
29
+ | `/prestations-ng/beta/` | NEXT |
30
+ | `/prestations-ng/lts/` | LTS |
31
+ | `/prestations-ng/lts/beta/` | NEXT of the LTS line, older than the beta in place (created by the first one) |
32
+
33
+ The documentation of a release never replaces a more recent one: a patch of an older minor version (e.g. 19.1.4 once
34
+ 19.2.0 is published) or a beta of a release branch other than the LTS one publishes nothing. Whatever the released
35
+ branch, Jenkins runs the scripts of `build-scripts/github-pages` of master (see `jenkins/Release.groovy`): they must
36
+ keep working with the Node version and the dependencies of the oldest branch still released.
37
+
38
+ Each publication:
39
+
40
+ - records its version in a `versions.json` written next to each `index.html`. The version switcher of the Dev Tool
41
+ (`src/app/core/version-switcher`), placed in the empty language column of the header, lists the other documentations,
42
+ except a beta whose version is published, and keeps the page displayed. `npm start` serves a demo `versions.json`
43
+ (`src/dev-assets`), where the local app is labelled `Local`;
44
+ - updates the shared `404.html` and adds the URL restoration to the index of each documentation, so deep links return
45
+ to the correct one. GitHub Pages still returns HTTP 404 for the initial deep-link request. Keep the places of
46
+ `github-pages.js`, the fallback and the restoration script in sync.
47
+
48
+ To publish the documentation of a checkout by hand (e.g. a branch without a release), from its root, with its
49
+ `node_modules` installed and the rights to push to the GitHub repository:
50
+
51
+ ```bash
52
+ git fetch origin master
53
+ mkdir -p node_modules/.cache/github-pages-scripts
54
+ git archive FETCH_HEAD build-scripts/github-pages | tar -x -C node_modules/.cache/github-pages-scripts
55
+ node node_modules/.cache/github-pages-scripts/build-scripts/github-pages/publish-doc.js STABLE # or LTS, NEXT
56
+ ```
28
57
 
29
58
  ## Testing the library in integration
30
59
 
@@ -34,7 +63,7 @@ result.
34
63
 
35
64
  ### In **prestations-ng**
36
65
 
37
- - if it is the first time, execute `npm install` then `npm run build:lib` (at root level)
66
+ - if it is the first time, execute `npm ci` then `npm run build:lib` (at root level)
38
67
  - `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
39
68
  - `cd ../.. && npm run build:lib:dev` (at root level)
40
69
 
@@ -73,7 +102,7 @@ run `npm run test:schematics` (at root level).
73
102
  ### Testing into a project such as **skeleton**
74
103
 
75
104
  - **In prestations-ng**:
76
- - if it is the first time, execute `npm install` then `npm run build:lib` (at root level)
105
+ - if it is the first time, execute `npm ci` then `npm run build:lib` (at root level)
77
106
  - `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
78
107
  - `cd ../.. && npm run build:lib:dev` (at root level)
79
108
 
@@ -117,7 +146,10 @@ use the correct node version in the settings, otherwise it might fail. Same thin
117
146
  - **Make sure you have installed pre commit hook by running :** `npm run huskyInstall`
118
147
  - Remove unnecessary `console.log`
119
148
  - Update [CHANGELOG.md](CHANGELOG.md)
120
- - Have it up to date with `npm install`
149
+ - Install the dependencies of `package-lock.json` with `npm ci` after each pull or change of branch that changed it
150
+ (Renovate updates it every week): the tests and the lint then run on the versions Jenkins installs. Not with
151
+ `npm install` or `npm update`, which may rewrite the lock file: the dependencies are updated by the PRs of Renovate,
152
+ never in another change.
121
153
  - If you want to autofix lint/format errors in your code : `npm run format`
122
154
  - Run all tests `npm run validate`
123
155
  - Ensure the commit message contains a Jira reference
@@ -138,7 +170,11 @@ Please make sure you have followed the **Before committing** section so you will
138
170
  The library ships its own ESLint plugin (see [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)). Its rules
139
171
  reach every consuming project through shareable configs, so **adding a rule breaks the lint of
140
172
  those projects on their next `npm update`**. That is the intent, but it makes the checklist
141
- below mandatory:
173
+ below mandatory.
174
+
175
+ First check that no rule covers the case already: the rules of the plugin (extend one, or keep
176
+ the messages of overlapping rules consistent), those of `@angular-eslint`, `typescript-eslint`
177
+ and ESLint (enable it in a config of `configs/` rather than writing a new one).
142
178
 
143
179
  1. Write the rule in `projects/prestations-ng/src/eslint/rules/<rule-name>.mjs`
144
180
  2. Register it in `rules/index.mjs`, keyed by its public kebab-case name
@@ -174,6 +210,8 @@ Please use the dedicated Jenkins build:
174
210
  - Choose **STABLE** in **NPM_TAG** when certain that your release is stable otherwise choose **NEXT** which will publish a **v1.2.3-BETA** on NPM
175
211
  - Check **RUN_TEST** if you wish to validate the library's test (can take a while)
176
212
 
213
+ The release also publishes its documentation (see [GitHub Pages documentation](#github-pages-documentation)).
214
+
177
215
  Alternatively, you can manually publish the package. Although this method is not recommended.
178
216
 
179
217
  - Ensure you can push to the npm registry: `npm adduser --registry=https://registry.npmjs.org --scope=@dsivd`
@@ -242,8 +280,10 @@ mechanism inherited from zone.js:
242
280
  - React to a signal input with `computed()` or `linkedSignal()`, not with `ngOnChanges()`.
243
281
  - Never mutate a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new array or
244
282
  object. No copy is then needed "so that the change detection sees a new reference".
245
- - Asynchronous work: set a signal in the callback, or convert the `Observable` with `toSignal()` where it is
246
- displayed. The services keep returning `Observable`s.
283
+ - Asynchronous work: data read by a GET is an `httpResource()`, or an `rxResource()` over the method of a service
284
+ (Angular 21 has the API of Angular 22, where they are stable), read behind `hasValue()`. Otherwise set a signal in
285
+ the callback, or convert the `Observable` with `toSignal()` where it is displayed. The services keep returning
286
+ `Observable`s.
247
287
  - `markForCheck()` only for a state that can't be a signal (e.g. the plain fields that the pages of the projects set
248
288
  when their form is loaded: `AbstractPageComponent` marks the page then).
249
289
  - Act on the rendered DOM (focus, scroll, measure) with `afterNextRender(..., { injector })`, never with
@@ -293,6 +333,8 @@ Neither the library nor the Dev Tool uses zone.js: the tests are **zoneless** to
293
333
  `userInput` of the inputs), not for the timers, nor for the HTTP requests of a spec: `provideHttpClientTesting()`
294
334
  keeps them pending until the test answers them with `HttpTestingController`. Answer them first, then
295
335
  `await fixture.whenStable()`.
336
+ - A loading resource (`httpResource()`, `rxResource()`) is a pending task: start its request with `TestBed.tick()`,
337
+ answer it, then `await fixture.whenStable()`.
296
338
  - Without zone.js, `fixture.detectChanges()` only refreshes the views that have been notified. A test (or a test
297
339
  host component) changing the state of a component must use signals, as the components do.
298
340
 
package/ESLINT_PLUGIN.md CHANGED
@@ -48,12 +48,12 @@ from the config. Inline templates written in a `@Component` are covered too, thr
48
48
 
49
49
  ## The configs
50
50
 
51
- | Config | Target | Contents |
52
- | ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
53
- | `configs.tsRecommended` | `**/*.ts` | the baselines, the house style, and `tsRules` |
54
- | `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules` |
55
- | `configs.tsRules` | `**/*.ts` | `no-direct-signal-mutation` |
56
- | `configs.templateRules` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, `require-model-change`, `no-item-track-in-form-list` |
51
+ | Config | Target | Contents |
52
+ | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
53
+ | `configs.tsRecommended` | `**/*.ts` | the baselines, the house style, and `tsRules` |
54
+ | `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules` |
55
+ | `configs.tsRules` | `**/*.ts` | `no-direct-signal-mutation` |
56
+ | `configs.templateRules` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, `require-model-change`, `no-item-track-in-form-list`, `require-track-index` |
57
57
 
58
58
  The `*Recommended` presets are what a project normally extends. On top of the rules written
59
59
  here they bring:
@@ -138,7 +138,8 @@ this.settings.update((current) => ({
138
138
  > component alone.
139
139
 
140
140
  All the assignment operators accepted by the Angular expression parser are covered: `=`,
141
- `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`.
141
+ `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`, and in TypeScript the increments
142
+ `++` and `--` (since 19.2.0-beta.29).
142
143
 
143
144
  The in-place mutators covered are those of `Array` — `push`, `pop`, `shift`, `unshift`,
144
145
  `splice`, `sort`, `reverse`, `fill`, `copyWithin` — and of `Map` / `Set` — `set`, `add`,
@@ -195,7 +196,8 @@ introduces the name — nothing is inferred from a naming convention. A variable
195
196
  for `reduce`, whose first parameter is the accumulator and not an element.
196
197
 
197
198
  **What it cannot follow** is a value crossing a function boundary — handed to a method,
198
- stored in a class field, returned and mutated elsewhere:
199
+ stored in a class field, returned by a method and mutated elsewhere (a getter is followed, see
200
+ below):
199
201
 
200
202
  ```ts
201
203
  // not reported: the rule cannot know what `sortInto` does
@@ -205,6 +207,56 @@ this.sortInto(this.settings().users);
205
207
  That needs interprocedural analysis, which ESLint does not provide; a full type checker
206
208
  would be required. It is the one remaining gap in detection.
207
209
 
210
+ #### Getters handing out the value
211
+
212
+ Since 19.2.0-beta.29, a getter of the class whose body is a single `return` of the value of
213
+ one of its signals, or of a part of it, is followed too: what it returns is that value. Such
214
+ getters are common in the pages, written before their form became a signal, and neither the
215
+ `ng update` migration nor the rule saw the writes through them until then:
216
+
217
+ ```ts
218
+ // in the page, or in an abstract page it extends
219
+ get step(): Step {
220
+ return this.form()!.etape;
221
+ }
222
+
223
+ // ✗ writes into the form, no notification
224
+ this.step.motif = value;
225
+ this.step.documents.push(document);
226
+
227
+ // ✓
228
+ this.patchForm(['etape', 'motif'], value);
229
+ this.patchForm(['etape', 'documents'], [...(this.step.documents ?? []), document]);
230
+ ```
231
+
232
+ ```angular-html
233
+ <!-- ✗ -->
234
+ <foehn-input-text name="motif" [(model)]="step.motif" />
235
+
236
+ <!-- ✓ -->
237
+ <foehn-input-text
238
+ name="motif"
239
+ [model]="step.motif"
240
+ (modelChange)="patchForm(['etape', 'motif'], $event)"
241
+ />
242
+ ```
243
+
244
+ The getter is resolved like the signals, through the inheritance chain (a getter of an
245
+ abstract page of your project is followed in its subclasses and their templates), and the
246
+ message names it with the signal: _Mutation of the value of the signal `form` through the
247
+ getter `step` detected_. A getter returning another such getter read further
248
+ (`get motif() { return this.step.motif; }`) is followed as well.
249
+
250
+ Left alone:
251
+
252
+ - the getter itself as the target (`this.step = value`, `[(step)]="step"`): it calls its
253
+ setter;
254
+ - a getter computing its value (`return this.form()?.etape ?? new Step();`, a copy, a
255
+ filter...) or made of more than a `return`: what it returns may not be the value of the
256
+ signal;
257
+ - a getter of a published library (its `.d.ts` has no body), and a name of the template
258
+ hiding the getter (`@for (step of steps; â€Ļ)`).
259
+
208
260
  #### Only real signals are inspected
209
261
 
210
262
  The rule does not guess from the shape of a call. It reads the declaring class — the linted
@@ -374,8 +426,7 @@ Applies to **templates only**.
374
426
  }
375
427
 
376
428
  <!-- ✓ -->
377
- @for (child of form.children; track child.id) { â€Ļ } @for (child of
378
- form.children; track $index) { â€Ļ }
429
+ @for (child of form.children; track $index) { â€Ļ }
379
430
  ```
380
431
 
381
432
  The list held by the `model` of a component is reported alike: a component extending
@@ -396,13 +447,59 @@ empty strings, even collide.
396
447
  A row edits its item when one of its elements has a `model` read from it
397
448
  (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
398
449
  the row (`[model]="model()[i]"`, `let i = $index`). A list only displayed, or read neither
399
- from the form nor from the model, is left alone. The rule suggests `track $index` (an
400
- identifier of the item is often better: it keeps the row of an item when the list is
401
- reordered).
450
+ from the form nor from the model, is left alone. The rule suggests `track $index`: the rows
451
+ of a list of the form name their fields with their index, which an identifier of the item
452
+ would break (see [`require-track-index`](#require-track-index), which reports these lists too:
453
+ the same `track` gets both messages, fixed by the same suggestion).
402
454
 
403
455
  > 💡 The control flow migration of Angular turns a `*ngFor` without `trackBy` into
404
456
  > `track <item>`: after it, check the lists of the form.
405
457
 
458
+ ### `require-track-index`
459
+
460
+ Reports a `@for` whose rows name their fields with the index of the row
461
+ (`[name]="'children[' + $index + '].firstName'"`, `name="child{{ i }}"`), or the errors of the
462
+ row (the `errorPrefix` of `foehn-error-pill`), tracked by anything else than `$index`. The
463
+ names of the fields follow the paths of the errors of GESDEM (`children[1].firstName`). Tracked
464
+ by an identifier of the item, a row whose item moves (an item removed before it, an item
465
+ inserted, the list sorted) is kept with its fields renamed: `foehn-form` keeps them registered
466
+ under their former names, so the row taking one of these names shares their `FormControl`, and
467
+ the errors, read by name when they are emitted, stay those of the former position. Tracked by
468
+ `$index`, a row never changes its names: only its item changes.
469
+
470
+ Applies to **templates only**. Suggests `track $index`.
471
+
472
+ ```html
473
+ <!-- ✗ an item removed before a child: the values and the errors of the rows get mixed up -->
474
+ @for (child of form.children; track child.id) {
475
+ <foehn-input-text
476
+ [name]="'children[' + $index + '].firstName'"
477
+ [model]="child.firstName"
478
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
479
+ />
480
+ }
481
+
482
+ <!-- ✓ -->
483
+ @for (child of form.children; track $index) {
484
+ <foehn-input-text
485
+ [name]="'children[' + $index + '].firstName'"
486
+ [model]="child.firstName"
487
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
488
+ />
489
+ }
490
+ ```
491
+
492
+ The index is `$index` or an alias of it (`let i = $index`), of the innermost `@for`
493
+ declaring the name: a name built with the index of an enclosing `@for`
494
+ (`'groups[' + g + '].children[' + $index + ']'`, `let g = $index`) reports that one too.
495
+ A name that doesn't depend on the position of the row (`'child-' + child.id`, a static
496
+ `name`) is left alone.
497
+
498
+ Limitations: a name built in the class of the component from the index (a method receiving
499
+ the item and looking up its index) isn't seen. The rule doesn't tell a list that never moves
500
+ (e.g. replaced as a whole) from one that does: tracking such a list by `$index` changes
501
+ nothing, the rows keep their names.
502
+
406
503
  ## The TypeScript counterpart
407
504
 
408
505
  `@angular-eslint/no-uncalled-signals` covers the same class of bug **in TypeScript**, using
package/GOOD_PRACTICES.md CHANGED
@@ -423,7 +423,7 @@ The `form` of a page is a signal: read it with `form()`, and never modify its va
423
423
  [model]="form.address.street"
424
424
  (modelChange)="patchForm(['address', 'street'], $event)"
425
425
  />
426
- @for (child of form.children; track child.id) {
426
+ @for (child of form.children; track $index) {
427
427
  <foehn-input-text
428
428
  [name]="'children[' + $index + '].firstName'"
429
429
  [model]="child.firstName"
@@ -444,9 +444,10 @@ addChild(): void {
444
444
  - Never a `[model]` alone on a field the user can change: what the user enters would never reach the form
445
445
  (`require-model-change` reports it). A field always disabled (`[disabled]="true"`), only displayed, is bound with
446
446
  `[model]` alone.
447
- - Track the rows of a list edited by its rows by an identifier (`track child.id`) or by `$index`, never by the
448
- item: `patchForm()` replaces it, the row would be created again and lose the focus (`no-item-track-in-form-list`
449
- reports it).
447
+ - Track the rows of the list by `$index`, as their names (`require-track-index` reports the others): tracked by an
448
+ identifier, a row whose item moves (an item removed before it, the list sorted) would keep the names of its former
449
+ position, and get the values and the errors of another row. Never by the item: `patchForm()` replaces it, the row
450
+ would be created again and lose the focus (`no-item-track-in-form-list` reports it).
450
451
  - A detail page (`AbstractListDetailPageComponent`) gives the path of its list with `getListPath()`, and writes the
451
452
  item edited with `patchItem()`, `updateItem()` or `setItem()`.
452
453
 
@@ -502,7 +503,9 @@ ngOnInit(): void {
502
503
  ```
503
504
 
504
505
  > 💡 For an observable displayed as is, `toSignal(this.myService.load())` or the `async` pipe do
505
- > the job for you.
506
+ > the job for you. For data read by a GET, `httpResource()` (or `rxResource()` over the service) also
507
+ > gives `isLoading()`, `hasValue()` and `error()` without a flag written by hand: see "`rxResource()`"
508
+ > in [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md).
506
509
 
507
510
  Do the same for a field read by the template that only a method called by a listener of the template
508
511
  modifies: the listener notifies Angular, but the same method can later be called from a `subscribe()`
@@ -1155,9 +1158,10 @@ prestation), passes its model through, without a copy:
1155
1158
 
1156
1159
  ### Avoiding error display problems in a `@for` loop
1157
1160
 
1158
- > âš ī¸ Don't forget to put a `track` with a unique identifier in the `@for` loop, otherwise the
1159
- > validation won't be displayed. When a unique identifier such as `id` isn't possible, track
1160
- > by `$index`: never by object a list of the form whose rows edit their item (see "Binding the fields of the form").
1161
+ > âš ī¸ Track the rows of the `@for` loop by `$index`, the index their fields are named with,
1162
+ > otherwise the validation is displayed on the wrong row once an item is removed or the list sorted
1163
+ > (`require-track-index` reports it). Never by object a list of the form whose rows edit their item
1164
+ > (see "Binding the fields of the form").
1161
1165
 
1162
1166
  > â„šī¸ In an Angular `@for` loop with a `FoehnInputComponent` component, if you validate your
1163
1167
  > form, the errors returned are synchronized with the index of your components repeated in the
@@ -1232,6 +1236,26 @@ export class YourPageComponent
1232
1236
  It's up to you to decide how to call this method when the item is removed from
1233
1237
  your list.
1234
1238
 
1239
+ A page handling the errors itself (see "Manual handling" in "Form validation") and keeping those of the server
1240
+ until its next save, e.g. a back office, has no validation to call: when it removes an item, it renumbers the errors
1241
+ with `removeListItemErrors()` of `ValidationHandlerService`. The errors of the removed item are dropped, and those of
1242
+ the following items take the new index of their item, the items of their nested lists included
1243
+ (`FormErrorHelper.withoutListItem()` does the same on an array of errors):
1244
+
1245
+ ```ts
1246
+ private readonly validationHandlerService = inject(ValidationHandlerService);
1247
+
1248
+ removeExchange(hearingIndex: number, exchangeIndex: number): void {
1249
+ // ... remove the exchange from the model, in a new array
1250
+ this.validationHandlerService.removeListItemErrors(
1251
+ `hearings[${hearingIndex}].exchanges[${exchangeIndex}]`,
1252
+ );
1253
+ }
1254
+ ```
1255
+
1256
+ No component of the library calls it: call it once per removal, and not besides a code of yours renumbering the
1257
+ errors already, or they would move twice.
1258
+
1235
1259
  Here is an elegant way to handle your lists of items:
1236
1260
 
1237
1261
  - Structure of the folders and files
@@ -1357,8 +1381,8 @@ export class VehiculeItemComponent extends FoehnInputComponent<Vehicule> {
1357
1381
  `vehicules-list.component.html` contains your `@for` loop (1) and your repeatable component (2), which
1358
1382
  must also send the event up.
1359
1383
 
1360
- > âš ī¸ In the `@for` loop, don't forget to put a `track`, otherwise the validation won't be
1361
- > displayed: an identifier every item has, even a new one, or `$index` as here. Never the item
1384
+ > âš ī¸ In the `@for` loop, track the rows by `$index`, as here: the names of the fields are built
1385
+ > with it, and the validation would otherwise be displayed on the wrong row. Never the item
1362
1386
  > itself (`track vehicule`): each change replaces it with a new vehicle, so its row would be created
1363
1387
  > again at each input, and the field being edited would lose the focus.
1364
1388