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

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/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,18 @@ 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).
40
51
  Detail pages: `getListPath()`, `list()`, `itemToEdit()`, and `patchItem()`, `updateItem()` or `setItem()`.
41
52
  - The `modelChange` of a `foehn-*` component is emitted only when the component writes its model (an input of the
42
53
  user, a correction), never when the page changes it (form loaded, prefill, reset). React to the loaded form where
@@ -90,8 +101,12 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
90
101
  `(userInput)` handler, the variable of a `@for`), has side effects, is overridden or implements a contract.
91
102
  - Never modify in place a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new
92
103
  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.
104
+ - Data read by a GET and displayed: `httpResource()` when the component builds the request, `rxResource()` over the
105
+ method of the service otherwise (Angular 21 has the API of Angular 22, where they are stable); read `value()` behind
106
+ `hasValue()`. It replaces a `subscribe()` setting the data and its loading or error flags by hand.
107
+ - Another `Observable` displayed: `toSignal()` or the `async` pipe where it's displayed; a `toSignal()` that works
108
+ stays. The services keep returning `Observable`s. Never give the `async` pipe a method or a getter returning a new
109
+ `Observable` at each read.
95
110
  - _Zoneless:_ a state read by a template and written by the code is a `signal()`, whoever writes it (a
96
111
  `subscribe()`, a promise, a timer, a hook, a method called by a listener). Act on the rendered DOM (focus, scroll)
97
112
  with `afterNextRender(..., { injector })`, never with `setTimeout()` or `NgZone`. `markForCheck()` only for a state
@@ -108,7 +123,8 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
108
123
  - Remove a method override only calling the parent method with the same arguments, and a constructor only calling
109
124
  `super()` (reported by `@typescript-eslint/no-useless-constructor`; see "A constructor only calling `super()`" in
110
125
  `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.
126
+ neither by its class, nor by a subclass, nor by their templates: no tool reports an unused `protected` or public
127
+ member.
112
128
  - The rules of the ESLint plugin of the library (`no-direct-signal-mutation`, `require-model-change`,
113
129
  `no-item-track-in-form-list`...) report the mistakes above: fix the code, don't turn them off.
114
130
 
@@ -120,3 +136,6 @@ applying the rules marked _strict_ or _zoneless_. The other rules apply to every
120
136
  `HttpTestingController`, then `await fixture.whenStable()`; with Vitest, `vi.useFakeTimers()` and
121
137
  `await vi.advanceTimersByTimeAsync(ms)` for the timers. A test changing the state of a component uses signals, as
122
138
  the components do. See "Testing a zoneless component" in `GOOD_PRACTICES.md`.
139
+ - A loading resource keeps `whenStable()` waiting for its response: start its request with a first change detection
140
+ (`TestBed.tick()`; with zone.js `fixture.detectChanges()`, `TestBed.tick()` throwing NG0101 there), answer it with
141
+ `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
@@ -45,6 +47,12 @@
45
47
  `(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
48
  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
49
  component, and a row reading its item at its index (`[model]="model()[i]"`).
50
+ - 🚨 ESLint rule [`require-track-index`](ESLINT_PLUGIN.md#require-track-index) (since 19.2.0-beta.28), in
51
+ `configs.templateRules` and `configs.templateRecommended`: a `@for` whose rows name their fields (or the
52
+ `errorPrefix` of `foehn-error-pill`) with the index of the row must track them by `$index`. Tracked by an identifier,
53
+ a row whose item moves (an item removed before it, the list sorted) keeps the names of its former position:
54
+ `foehn-form` keeps its fields registered under them, and the values and the errors of the rows get mixed up. To turn
55
+ it off: `'@dsivd/prestations-ng/require-track-index': 'off'`.
48
56
 
49
57
  - [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
50
58
  - New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
@@ -111,6 +119,14 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
111
119
  - `FoehnListSummaryComponent` is now generic: `FoehnListSummaryComponent<T extends FoehnListItem>`,
112
120
  so the model, `getListItemTitle` and `listItemDescriptions` are typed with your own item class
113
121
  instead of the base `FoehnListItem`
122
+ - The rows are tracked by their index (since 19.2.0-beta.28), as the prefix of their errors: sorted, a row no
123
+ longer keeps the errors of its former position. `trackFoehnListItem` returns the index, and the id of a row is
124
+ `list-summary-<its position from 1>` instead of `list-summary-<its trackingIndex>`.
125
+ - [foehn-list-item.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-item.ts)
126
+ - 🚨 `FoehnListItem.trackingIndex` is removed (since 19.2.0-beta.28): the library tracks the rows of a list by
127
+ their index (`require-track-index`). `AbstractListDetailPageComponent` no longer sets it on a new item, and its
128
+ `getNextTrackingIndex()` is removed. A project whose backend needs the field declares it in its item class and
129
+ sets it in `getNewListItem()` (see UPGRADING_V19.md).
114
130
  - [foehn-list-item-description.ts](projects/prestations-ng/src/foehn-menu-prestation/foehn-list-summary/foehn-list-item-description.ts)
115
131
  - 🚨 `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
116
132
  `getFormattedValue(item: T)` and `hideIfEmpty(item: T)` receive your item type directly, no cast needed.
@@ -212,6 +228,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
212
228
  abstract `getList()`, which reads the list at that path. `list`, `itemIndex` and `itemToEdit` are now signals. The
213
229
  item edited is written with the new `patchItem(path, value)`, `updateItem(update)` (several fields in one write)
214
230
  and `setItem(item)`. A new item is added without modifying the list of the form in place.
231
+ - 🚨 `SessionInfo` reads the `NEVER_CONNECTED` token (since 19.2.0-beta.1): a provider
232
+ `{ provide: 'neverConnected', useValue: true }` is ignored without any error, and the application fetches the
233
+ session and displays the connected user or the login button. Provide `{ provide: NEVER_CONNECTED, useValue: true }`
234
+ instead. The `ng update` migration rewrites the providers, see
235
+ [UPGRADING_V19.md](UPGRADING_V19.md#neverconnected-is-provided-with-never_connected-since-1920).
215
236
  - `PendingUploadService` writes the documents uploaded with the form into a new form, instead of modifying the form
216
237
  in place.
217
238
  - 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) sees through the
@@ -283,6 +304,8 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
283
304
 
284
305
  ### Fixed
285
306
 
307
+ - `foehn-checkbox` and `foehn-agenda` track their rows by their index (since 19.2.0-beta.28), as the names of their
308
+ fields: the checkboxes of elements reordered or replaced no longer share the control of the former ones.
286
309
  - 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
287
310
  `elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
288
311
  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
@@ -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
 
@@ -138,7 +167,11 @@ Please make sure you have followed the **Before committing** section so you will
138
167
  The library ships its own ESLint plugin (see [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)). Its rules
139
168
  reach every consuming project through shareable configs, so **adding a rule breaks the lint of
140
169
  those projects on their next `npm update`**. That is the intent, but it makes the checklist
141
- below mandatory:
170
+ below mandatory.
171
+
172
+ First check that no rule covers the case already: the rules of the plugin (extend one, or keep
173
+ the messages of overlapping rules consistent), those of `@angular-eslint`, `typescript-eslint`
174
+ and ESLint (enable it in a config of `configs/` rather than writing a new one).
142
175
 
143
176
  1. Write the rule in `projects/prestations-ng/src/eslint/rules/<rule-name>.mjs`
144
177
  2. Register it in `rules/index.mjs`, keyed by its public kebab-case name
@@ -174,6 +207,8 @@ Please use the dedicated Jenkins build:
174
207
  - 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
208
  - Check **RUN_TEST** if you wish to validate the library's test (can take a while)
176
209
 
210
+ The release also publishes its documentation (see [GitHub Pages documentation](#github-pages-documentation)).
211
+
177
212
  Alternatively, you can manually publish the package. Although this method is not recommended.
178
213
 
179
214
  - Ensure you can push to the npm registry: `npm adduser --registry=https://registry.npmjs.org --scope=@dsivd`
@@ -242,8 +277,10 @@ mechanism inherited from zone.js:
242
277
  - React to a signal input with `computed()` or `linkedSignal()`, not with `ngOnChanges()`.
243
278
  - Never mutate a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new array or
244
279
  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.
280
+ - Asynchronous work: data read by a GET is an `httpResource()`, or an `rxResource()` over the method of a service
281
+ (Angular 21 has the API of Angular 22, where they are stable), read behind `hasValue()`. Otherwise set a signal in
282
+ the callback, or convert the `Observable` with `toSignal()` where it is displayed. The services keep returning
283
+ `Observable`s.
247
284
  - `markForCheck()` only for a state that can't be a signal (e.g. the plain fields that the pages of the projects set
248
285
  when their form is loaded: `AbstractPageComponent` marks the page then).
249
286
  - Act on the rendered DOM (focus, scroll, measure) with `afterNextRender(..., { injector })`, never with
@@ -293,6 +330,8 @@ Neither the library nor the Dev Tool uses zone.js: the tests are **zoneless** to
293
330
  `userInput` of the inputs), not for the timers, nor for the HTTP requests of a spec: `provideHttpClientTesting()`
294
331
  keeps them pending until the test answers them with `HttpTestingController`. Answer them first, then
295
332
  `await fixture.whenStable()`.
333
+ - A loading resource (`httpResource()`, `rxResource()`) is a pending task: start its request with `TestBed.tick()`,
334
+ answer it, then `await fixture.whenStable()`.
296
335
  - Without zone.js, `fixture.detectChanges()` only refreshes the views that have been notified. A test (or a test
297
336
  host component) changing the state of a component must use signals, as the components do.
298
337
 
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:
@@ -374,8 +374,7 @@ Applies to **templates only**.
374
374
  }
375
375
 
376
376
  <!-- ✓ -->
377
- @for (child of form.children; track child.id) { … } @for (child of
378
- form.children; track $index) { … }
377
+ @for (child of form.children; track $index) { … }
379
378
  ```
380
379
 
381
380
  The list held by the `model` of a component is reported alike: a component extending
@@ -396,13 +395,59 @@ empty strings, even collide.
396
395
  A row edits its item when one of its elements has a `model` read from it
397
396
  (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
398
397
  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).
398
+ from the form nor from the model, is left alone. The rule suggests `track $index`: the rows
399
+ of a list of the form name their fields with their index, which an identifier of the item
400
+ would break (see [`require-track-index`](#require-track-index), which reports these lists too:
401
+ the same `track` gets both messages, fixed by the same suggestion).
402
402
 
403
403
  > 💡 The control flow migration of Angular turns a `*ngFor` without `trackBy` into
404
404
  > `track <item>`: after it, check the lists of the form.
405
405
 
406
+ ### `require-track-index`
407
+
408
+ Reports a `@for` whose rows name their fields with the index of the row
409
+ (`[name]="'children[' + $index + '].firstName'"`, `name="child{{ i }}"`), or the errors of the
410
+ row (the `errorPrefix` of `foehn-error-pill`), tracked by anything else than `$index`. The
411
+ names of the fields follow the paths of the errors of GESDEM (`children[1].firstName`). Tracked
412
+ by an identifier of the item, a row whose item moves (an item removed before it, an item
413
+ inserted, the list sorted) is kept with its fields renamed: `foehn-form` keeps them registered
414
+ under their former names, so the row taking one of these names shares their `FormControl`, and
415
+ the errors, read by name when they are emitted, stay those of the former position. Tracked by
416
+ `$index`, a row never changes its names: only its item changes.
417
+
418
+ Applies to **templates only**. Suggests `track $index`.
419
+
420
+ ```html
421
+ <!-- ✗ an item removed before a child: the values and the errors of the rows get mixed up -->
422
+ @for (child of form.children; track child.id) {
423
+ <foehn-input-text
424
+ [name]="'children[' + $index + '].firstName'"
425
+ [model]="child.firstName"
426
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
427
+ />
428
+ }
429
+
430
+ <!-- ✓ -->
431
+ @for (child of form.children; track $index) {
432
+ <foehn-input-text
433
+ [name]="'children[' + $index + '].firstName'"
434
+ [model]="child.firstName"
435
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
436
+ />
437
+ }
438
+ ```
439
+
440
+ The index is `$index` or an alias of it (`let i = $index`), of the innermost `@for`
441
+ declaring the name: a name built with the index of an enclosing `@for`
442
+ (`'groups[' + g + '].children[' + $index + ']'`, `let g = $index`) reports that one too.
443
+ A name that doesn't depend on the position of the row (`'child-' + child.id`, a static
444
+ `name`) is left alone.
445
+
446
+ Limitations: a name built in the class of the component from the index (a method receiving
447
+ the item and looking up its index) isn't seen. The rule doesn't tell a list that never moves
448
+ (e.g. replaced as a whole) from one that does: tracking such a list by `$index` changes
449
+ nothing, the rows keep their names.
450
+
406
451
  ## The TypeScript counterpart
407
452
 
408
453
  `@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
@@ -1357,8 +1361,8 @@ export class VehiculeItemComponent extends FoehnInputComponent<Vehicule> {
1357
1361
  `vehicules-list.component.html` contains your `@for` loop (1) and your repeatable component (2), which
1358
1362
  must also send the event up.
1359
1363
 
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
1364
+ > ⚠️ In the `@for` loop, track the rows by `$index`, as here: the names of the fields are built
1365
+ > with it, and the validation would otherwise be displayed on the wrong row. Never the item
1362
1366
  > itself (`track vehicule`): each change replaces it with a new vehicle, so its row would be created
1363
1367
  > again at each input, and the field being edited would lose the focus.
1364
1368
 
package/UPGRADING_V19.md CHANGED
@@ -308,10 +308,11 @@ ng update @angular/core@20 @angular/cli@20
308
308
  - accept **"router-current-navigation"** by hitting "Space" key
309
309
  - hit "Enter" key
310
310
 
311
- 🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present and has a unique identifier.
312
- When a unique identifier such as `id` is not possible, track by object or as a last resort use `track $index`. Since
313
- 19.2.0, never track by object a list of the form whose rows edit their item: track it by `id` or by `$index` (see
314
- "The form of your pages is a signal").**
311
+ 🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present. Track by
312
+ `$index` the rows naming their fields with the index (`[name]="'children[' + $index + '].firstName'"`, every list of
313
+ the form): tracked by an identifier, a row whose item moves keeps the names of its former position and gets the
314
+ values and the errors of another row (`require-track-index`, since 19.2.0). Since 19.2.0, never track by object a list
315
+ of the form whose rows edit their item (see "The form of your pages is a signal").**
315
316
 
316
317
  💡 **NB: When using `@angular/cdk` in your project**
317
318
 
@@ -394,6 +395,55 @@ ng update ngx-matomo-client@9
394
395
 
395
396
  💡 **NB: Upgrade all other libraries needed by your project (such as: primeng, lodash, ...) to their latest version compatible with angular 21**
396
397
 
398
+ ### Instructions for your AI assistant (since 19.2.0)
399
+
400
+ The library ships [AI_GUIDELINES.md](AI_GUIDELINES.md): the rules an AI assistant (Claude Code, GitHub Copilot...)
401
+ follows in a project using it, for the version installed. Give them to your assistant now, so that it follows them
402
+ for the rest of this migration. The versions before 19.2.0 (e.g. 19.1.x) don't have the file: skip this step, and come
403
+ back to it once you upgrade to 19.2.0.
404
+
405
+ At the root of the project holding the front (not in the `front` folder):
406
+
407
+ 1. For Claude Code, create the `.claude` folder and its `CLAUDE.md` file if they don't exist, and add the import of
408
+ the file, its path being relative to `CLAUDE.md`:
409
+
410
+ ```text
411
+ @../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
412
+ ```
413
+
414
+ 2. For the other assistants (GitHub Copilot, Codex, Cursor...), create the `AGENTS.md` file if it doesn't exist, and
415
+ add this sentence to it: they read `AGENTS.md`, but can't import a file.
416
+
417
+ ```text
418
+ Before changing the front, read and follow `front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`:
419
+ the rules of the installed version of `@dsivd/prestations-ng`.
420
+ ```
421
+
422
+ Then:
423
+
424
+ - The project is your repository or, in a repository holding several projects (e.g. `my-project-fo/front` and
425
+ `my-project-bo/front`), the folder of each one: each project gets its own `.claude/CLAUDE.md` and `AGENTS.md`, with
426
+ the rules of its version of `prestations-ng`. Claude Code loads `.claude/CLAUDE.md` when it's started in the
427
+ project or one of its folders (e.g. `front`) or, started at the root of the repository, as soon as it reads a file
428
+ of the project.
429
+ - If the project already has a `CLAUDE.md` at its root, add the import there rather than creating a second file:
430
+ `@front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
431
+ - A project with several fronts, or an Angular library shared by the fronts of the repository: both files in the
432
+ folder of each one, next to its `node_modules`, with `@../node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md` and
433
+ `node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
434
+ - Keep the import in `.claude/CLAUDE.md` even with `AGENTS.md`: Claude Code reads `AGENTS.md` only in a folder
435
+ without `CLAUDE.md`, and not in every mode.
436
+ - An import loads nothing until the dependencies of its front are installed (`npm ci` after a clone): until then,
437
+ your assistant doesn't have the rules.
438
+ - Commit `.claude/CLAUDE.md` and `AGENTS.md`, so that the whole team gets the rules, but not the permissions each
439
+ developer grants to Claude Code for the project, which it keeps in `.claude/settings.local.json`: add
440
+ `**/.claude/settings.local.json` to the `.gitignore` of your repository.
441
+ - Refer to the file rather than copying it: the rules follow the version installed at each upgrade, those of
442
+ Renovate included, without changing your files.
443
+
444
+ 💡 **NB: The rules describe the code once migrated. Your assistant follows the steps of this guide in order, without
445
+ anticipating the next ones: `AI_GUIDELINES.md` tells it so.**
446
+
397
447
  ### Quick fix
398
448
 
399
449
  - In all custom components extending `FoehnInputComponent`, in `providers` providing `FoehnInputComponent` remove `multi: true,`.
@@ -1603,6 +1653,20 @@ removed item stays in the form and comes back when the form is saved. In a page,
1603
1653
  }
1604
1654
  ```
1605
1655
 
1656
+ ### `FoehnListItem` has no `trackingIndex` (since 19.2.0)
1657
+
1658
+ The library tracks the rows of a list by their index (see `require-track-index` in [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)):
1659
+ `FoehnListItem.trackingIndex` is removed, and `AbstractListDetailPageComponent` no longer sets it on a new item
1660
+ (`getNextTrackingIndex()` is removed too). The id of a row of `foehn-list-summary` is `list-summary-<its position
1661
+ from 1>`.
1662
+
1663
+ - Track your lists by `$index`, not by `item.trackingIndex`.
1664
+ - The code reading `trackingIndex` on an item typed with `FoehnListItem`, or calling or overriding
1665
+ `getNextTrackingIndex()`, no longer compiles: remove it.
1666
+ - 🚨 Nothing reports a backend needing the field (e.g. a `@NotNull trackingIndex`, a list sorted by it): a new item
1667
+ now reaches it without one. Remove the field from the backend and from its data, or, to keep it, declare it in your
1668
+ item class and set it in `getNewListItem()`.
1669
+
1606
1670
  ### `core-js` is no longer needed (since 19.2.0)
1607
1671
 
1608
1672
  prestations-ng no longer imports `core-js` and no longer has it as a peer dependency. If your project does not
@@ -1756,8 +1820,9 @@ Also check:
1756
1820
 
1757
1821
  `patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
1758
1822
  is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
1759
- list edited by its rows by an identifier of the item (`track child.id`), or by `$index`. The migration does it for the
1760
- lists it migrates, and `no-item-track-in-form-list` (`configs.templateRecommended`) reports the others.
1823
+ list edited by its rows by `$index`, the index naming their fields (an identifier of the item, `track child.id`, only
1824
+ when they name nothing with it). The migration does it for the lists it migrates, and `no-item-track-in-form-list`
1825
+ and `require-track-index` (`configs.templateRecommended`) report the others.
1761
1826
 
1762
1827
  #### Write your templates
1763
1828
 
@@ -1807,6 +1872,20 @@ getListPath(): ObjectPath<ApForm | AfForm> {
1807
1872
  }
1808
1873
  ```
1809
1874
 
1875
+ ### `neverConnected` is provided with `NEVER_CONNECTED` (since 19.2.0)
1876
+
1877
+ `SessionInfo` reads the `NEVER_CONNECTED` token: a provider `{ provide: 'neverConnected', useValue: true }` is ignored
1878
+ without any error, and your application fetches the session and displays the connected user or the login button.
1879
+ `ng update @dsivd/prestations-ng` replaces it (see "Run the migration" above to run it by hand):
1880
+
1881
+ ```diff
1882
+ - { provide: 'neverConnected', useValue: true },
1883
+ + { provide: NEVER_CONNECTED, useValue: true },
1884
+ ```
1885
+
1886
+ with `NEVER_CONNECTED` imported from `@dsivd/prestations-ng`. It lists the other uses of the string `'neverConnected'`
1887
+ it doesn't rewrite: search them in your providers, e.g. a value coming from a constant or a shared library.
1888
+
1810
1889
  ### Zoneless (optional but recommended)
1811
1890
 
1812
1891
  Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
@@ -20,6 +20,9 @@ const templateRules = (plugin) => [
20
20
  // loses the focus at every input
21
21
  '@dsivd/prestations-ng/require-model-change': 'error',
22
22
  '@dsivd/prestations-ng/no-item-track-in-form-list': 'error',
23
+ // The rows naming their fields with their index keep these names
24
+ // only when tracked by $index
25
+ '@dsivd/prestations-ng/require-track-index': 'error',
23
26
  },
24
27
  },
25
28
  ];
@@ -2,10 +2,12 @@ import noDirectSignalMutation from './no-direct-signal-mutation.mjs';
2
2
  import noItemTrackInFormList from './no-item-track-in-form-list.mjs';
3
3
  import noUninvokedSignalInTemplate from './no-uninvoked-signal-in-template.mjs';
4
4
  import requireModelChange from './require-model-change.mjs';
5
+ import requireTrackIndex from './require-track-index.mjs';
5
6
 
6
7
  export default {
7
8
  'no-direct-signal-mutation': noDirectSignalMutation,
8
9
  'no-item-track-in-form-list': noItemTrackInFormList,
9
10
  'no-uninvoked-signal-in-template': noUninvokedSignalInTemplate,
10
11
  'require-model-change': requireModelChange,
12
+ 'require-track-index': requireTrackIndex,
11
13
  };
@@ -11,8 +11,9 @@ import { astOf, resolveRoot } from "../form-reads.mjs";
11
11
  * `FoehnInputComponent` writes a new list in its model, its items replaced (`updateNgModel()`).
12
12
  * A row tracked by its item is then destroyed and created again at every input, and the field
13
13
  * being edited loses the focus; two items equal by value (e.g. two empty strings) even collide.
14
- * Track the rows by `$index`, or by an identifier of the item (`track child.id`), which the copy
15
- * keeps.
14
+ * Track the rows by `$index`: an identifier of the item (`track child.id`), which the copy keeps,
15
+ * only when the rows name nothing with their index (see `require-track-index`, which reports
16
+ * these lists too when they do).
16
17
  *
17
18
  * A row edits its item when one of its elements has a `model` read from it
18
19
  * (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
@@ -108,7 +109,7 @@ export default {
108
109
  schema: [],
109
110
  messages: {
110
111
  itemTrack:
111
- "The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, so its row is created again and the field being edited loses the focus. Track the rows by $index or by an identifier of the item.",
112
+ "The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, so its row is created again and the field being edited loses the focus. Track the rows by $index (by an identifier of the item only when the rows name nothing with their index).",
112
113
  trackByIndex: "Track the rows by $index",
113
114
  },
114
115
  },