@dsivd/prestations-ng 19.2.0-beta.3 → 19.2.0-beta.30

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 (65) hide show
  1. package/AI_GUIDELINES.md +152 -0
  2. package/ANGULAR_SIGNALS.md +6 -2
  3. package/CHANGELOG.md +476 -0
  4. package/CONTRIBUTING.md +128 -8
  5. package/ESLINT_PLUGIN.md +262 -30
  6. package/GOOD_PRACTICES.md +983 -388
  7. package/INTRODUCTION_ANGULAR_SIGNALS.md +227 -155
  8. package/README.md +22 -12
  9. package/UPGRADING_V18.md +5 -5
  10. package/UPGRADING_V19.md +636 -19
  11. package/eslint/configs/spec-ts-recommended.mjs +34 -0
  12. package/eslint/configs/template-recommended.mjs +2 -0
  13. package/eslint/configs/template-rules.mjs +14 -2
  14. package/eslint/configs/ts-recommended.mjs +11 -0
  15. package/eslint/configs/ts-rules.mjs +6 -2
  16. package/eslint/form-reads.mjs +63 -0
  17. package/eslint/index.mjs +17 -0
  18. package/eslint/rules/index.mjs +6 -0
  19. package/eslint/rules/no-direct-signal-mutation.mjs +162 -41
  20. package/eslint/rules/no-item-track-in-form-list.mjs +173 -0
  21. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  22. package/eslint/rules/require-model-change.mjs +89 -0
  23. package/eslint/rules/require-track-index.mjs +162 -0
  24. package/eslint/signal-names.mjs +127 -21
  25. package/eslint/template-ast.mjs +12 -2
  26. package/fesm2022/dsivd-prestations-ng.mjs +2889 -2061
  27. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  28. package/package.json +1 -2
  29. package/schematics/migration-collection.json +5 -0
  30. package/schematics/ng-add/index.js +2 -4
  31. package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
  32. package/schematics/ng-update/migrations/update-19_2_0/index.js +52 -0
  33. package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
  34. package/schematics/utility/form-signal/class-migration.js +795 -0
  35. package/schematics/utility/form-signal/edits.js +34 -0
  36. package/schematics/utility/form-signal/form-members.js +318 -0
  37. package/schematics/utility/form-signal/form-signal-migration.js +134 -0
  38. package/schematics/utility/form-signal/page-classes.js +139 -0
  39. package/schematics/utility/form-signal/template-migration.js +775 -0
  40. package/schematics/utility/never-connected-migration.js +87 -0
  41. package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
  42. package/schematics/utility/typescript-files.js +95 -0
  43. package/src/eslint/configs/__tests__/configs.test.mjs +61 -2
  44. package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
  45. package/src/eslint/configs/template-recommended.mjs +2 -0
  46. package/src/eslint/configs/template-rules.mjs +14 -2
  47. package/src/eslint/configs/ts-recommended.mjs +11 -0
  48. package/src/eslint/configs/ts-rules.mjs +6 -2
  49. package/src/eslint/form-reads.mjs +63 -0
  50. package/src/eslint/index.mjs +17 -0
  51. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +200 -0
  52. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
  53. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  54. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  55. package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
  56. package/src/eslint/rules/index.mjs +6 -0
  57. package/src/eslint/rules/no-direct-signal-mutation.mjs +162 -41
  58. package/src/eslint/rules/no-item-track-in-form-list.mjs +173 -0
  59. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  60. package/src/eslint/rules/require-model-change.mjs +89 -0
  61. package/src/eslint/rules/require-track-index.mjs +162 -0
  62. package/src/eslint/signal-names.mjs +127 -21
  63. package/src/eslint/template-ast.mjs +12 -2
  64. package/types/dsivd-prestations-ng.d.ts +719 -243
  65. package/dsivd-prestations-ng-19.2.0-beta.3.tgz +0 -0
@@ -0,0 +1,152 @@
1
+ # Guidelines for AI assistants
2
+
3
+ The rules an AI assistant follows in a project using `@dsivd/prestations-ng`. This file is published with the
4
+ library and describes the version installed: import it into the instructions of your assistant rather than copying
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):
7
+
8
+ ```text
9
+ @../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
10
+ ```
11
+
12
+ The explanations and the examples are in `GOOD_PRACTICES.md` and `UPGRADING_V19.md`, next to this file.
13
+
14
+ ## Check the project first
15
+
16
+ The strict mode and the zoneless change detection are optional steps of the migration to v19: check them before
17
+ applying the rules marked _strict_ or _zoneless_. The other rules apply to every project.
18
+
19
+ - Strict: `"strict": true` in the `compilerOptions` of `tsconfig.json` (and `"strictTemplates": true` in its
20
+ `angularCompilerOptions`).
21
+ - Zoneless: `provideZonelessChangeDetection()` in the providers of the application, and no `zone.js` in the
22
+ `polyfills` of `angular.json`. Without zone.js, Angular refreshes a view only when a signal read by its template
23
+ changes, or when it's notified: the rules marked _zoneless_ are required. With zone.js, they're the way to write
24
+ new code, but the existing code works without them: change it only when asked (see "Zoneless" and "Strict mode" in
25
+ `UPGRADING_V19.md`).
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
+
30
+ ## The form of a page
31
+
32
+ - `AbstractPageComponent` replaces the form with the JSON of the backend as is: at runtime, a field has the type of
33
+ the Java model, whatever its TypeScript type says. When the backend is in the repository, check the Java type of a
34
+ field before writing code that reads it.
35
+ - `form` and `reference` are `WritableSignal`s: read `form()` and `reference()`. Write a field of the form with
36
+ `patchForm(path, value)` (a typed path, e.g. `['children', $index, 'firstName']`), the whole form with `form.set()`
37
+ or `form.update()` and a new object. Never modify the form in place, and no `markForCheck()` after a write.
38
+ - In the template, guard the fields with `@if (form(); as form)` inside `<foehn-form>`, which is never conditional
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.
53
+ Detail pages: `getListPath()`, `list()`, `itemToEdit()`, and `patchItem()`, `updateItem()` or `setItem()`.
54
+ - The `modelChange` of a `foehn-*` component is emitted only when the component writes its model (an input of the
55
+ user, a correction), never when the page changes it (form loaded, prefill, reset). React to the loaded form where
56
+ the page writes it, e.g. `GesdemEventService.formInitializationObservable()`.
57
+ - `reference()` is `undefined` until a form is loaded, `null` for a demand without reference: derive from it with
58
+ `computed()`. A request needing it is an `httpResource()` (or an `rxResource()` over a service) whose request
59
+ returns `undefined` while the reference is missing; read its `value()` only behind `hasValue()`.
60
+
61
+ ## The types of the fields
62
+
63
+ - The model of `foehn-input-number` is a `string` (`'0'` after an input), but the Java field is a number: once the
64
+ form comes back from the backend, it holds `0`. Same for any `string` model bound to a Java field which isn't a
65
+ `String`. Never test such a field by its truthiness (`!!x`, `if (x)`, `x || y`): compare it with `null` and `''`,
66
+ and convert it with `Number()` for a calculation.
67
+ - The values of the elements of `foehn-select` and `foehn-checkbox` have the type of the Java field: they are
68
+ compared to the model with `===` (`'1'` doesn't select `1`).
69
+ - A date is a `FoehnDateModel | null` (`[year, month, day]`, `LenientLocalDate` in Java), a date-time a
70
+ `FoehnDateTimeModel | null` (`[year, month, day, hour, minute]`, `LenientLocalDateTime`), a time a `string`
71
+ (`String` with `@ValidStringTime`). A part not entered is `null`, also once saved: never build a `Date` from it by
72
+ hand, use `DateHelper` and the `displayDate` pipe. See "Types of the form fields" in `GOOD_PRACTICES.md`.
73
+ - _Strict:_ a field the backend can omit or send as `null` is `T | null`, initialized with `null`, not `T` with a
74
+ `!`.
75
+
76
+ ## A component extending `FoehnInputComponent`
77
+
78
+ - Its model is a signal, which ignores the same reference: give `updateNgModel()` a new object or array, never the
79
+ model modified in place, or the page isn't notified. The inherited inputs are signals too: `this.name()`.
80
+ - A list reads its `model()` directly, binds its items with `[model]="item" (modelChange)="patchNgModel([i], $event)"`
81
+ and adds or removes one with a new array. Every change of a child reaches it through `modelChange`, not only
82
+ `userInput`.
83
+ - A component editing an object as is reads `model()` and writes a field with
84
+ `[model]="model()?.x" (modelChange)="patchNgModel(['x'], $event)"`. It overrides `emptyModel()`, after its public
85
+ members, when the page can give no object. Several fields at once:
86
+ `updateNgModel(Object.assign(new X(), this.model(), { a, b }))` (a spread loses the class). A rule applied at each
87
+ write, or `null` for an emptied object once `model_` is known: an override of `updateNgModel()` giving `super` the
88
+ corrected object. See "Editing an object field by field" in `GOOD_PRACTICES.md`.
89
+ - A component wrapping a single `foehn-*` component binds it with `[model]="model()"` and
90
+ `(modelChange)="updateNgModel($event)"`, never `[(model)]="model"`. See "Wrapping a single component".
91
+ - Only a component transforming its model (a date in three fields) has a `linkedSignal()` per field, derived from
92
+ `this.model`; when a field must keep its value on a partial model, use
93
+ `{ source: this.model, computation: (value, previous) => ... }`. No `onModelChange()` override copying the model.
94
+
95
+ ## Signals
96
+
97
+ - Derived state: a `computed()`, or a `linkedSignal()` when it can also be changed locally; never a signal kept in
98
+ sync from `ngOnChanges()`, an `effect()` or a `setTimeout()`.
99
+ - A method or a getter deriving a value only from signals becomes a `computed()` of the same name (a getter gains
100
+ `()`), and so does a method all of whose calls give it the same value read from a signal (the `computed()` reads
101
+ that signal itself). Only when everything it reads is a signal: a plain field, a service state that isn't a signal
102
+ or the DOM would leave it stale. Keep a method when its calls give it different values (e.g. the new value in a
103
+ `(userInput)` handler, the variable of a `@for`), has side effects, is overridden or implements a contract.
104
+ - Never modify in place a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new
105
+ array or object.
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.
112
+ - _Zoneless:_ a state read by a template and written by the code is a `signal()`, whoever writes it (a
113
+ `subscribe()`, a promise, a timer, a hook, a method called by a listener). Act on the rendered DOM (focus, scroll)
114
+ with `afterNextRender(..., { injector })`, never with `setTimeout()` or `NgZone`. `markForCheck()` only for a state
115
+ that can't be a signal. `effect()` as a last resort, with `untracked()`. See "Zoneless application" in
116
+ `GOOD_PRACTICES.md`.
117
+ - Before changing existing code, ask whether it would be written this way today: `setTimeout()`, `NgZone`,
118
+ `ngOnChanges()` and copies made "for the change detection" are often zone.js leftovers.
119
+
120
+ ## HTTP errors and file downloads
121
+
122
+ - For an HTTP service that reports failures with a growl, extend `AbstractHttpService` and use
123
+ `catchError(this.catchError(this._dictionaryService.getKeySync('your-request.error')))` with a dictionary key
124
+ from the project. The handler prefers a message from the server and propagates the error to the caller.
125
+ - Use `downloadFile(data, filename, type)` for browser downloads from in-memory data. Pass the media type when
126
+ known. Import both helpers from `@dsivd/prestations-ng`. See “HTTP errors and file downloads” in
127
+ [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
128
+
129
+ ## TypeScript
130
+
131
+ - Never silence the compiler or the linter: no `any`, `as any`, `as unknown as X`, `@ts-ignore`, `eslint-disable`.
132
+ - _Strict:_ a non-null assertion `!` only when the invariant is guaranteed and visible right there; otherwise narrow
133
+ (`if`, early return, `??`, `?.`) or fix the type where the value comes from.
134
+ - Remove a method override only calling the parent method with the same arguments, and a constructor only calling
135
+ `super()` (reported by `@typescript-eslint/no-useless-constructor`; see "A constructor only calling `super()`" in
136
+ `ESLINT_PLUGIN.md` for a parent with a `protected` constructor). Remove an `inject()` field or an `input()` read
137
+ neither by its class, nor by a subclass, nor by their templates: no tool reports an unused `protected` or public
138
+ member.
139
+ - The rules of the ESLint plugin of the library (`no-direct-signal-mutation`, `require-model-change`,
140
+ `no-item-track-in-form-list`...) report the mistakes above: fix the code, don't turn them off.
141
+
142
+ ## Tests
143
+
144
+ - No `expect()` inside a `subscribe()`: `const value = firstValueFrom(obs$)` before triggering, then `await value`.
145
+ No `await` inside `expect()`.
146
+ - _Zoneless:_ `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` need zone.js. Answer the HTTP requests with
147
+ `HttpTestingController`, then `await fixture.whenStable()`; with Vitest, `vi.useFakeTimers()` and
148
+ `await vi.advanceTimersByTimeAsync(ms)` for the timers. A test changing the state of a component uses signals, as
149
+ the components do. See "Testing a zoneless component" in `GOOD_PRACTICES.md`.
150
+ - A loading resource keeps `whenStable()` waiting for its response: start its request with a first change detection
151
+ (`TestBed.tick()`; with zone.js `fixture.detectChanges()`, `TestBed.tick()` throwing NG0101 there), answer it with
152
+ `HttpTestingController`, then `await fixture.whenStable()`.
@@ -866,6 +866,10 @@ this.address.update((current) => ({
866
866
  ...current,
867
867
  locality: { ...current.locality, name: 'newName' },
868
868
  }));
869
+
870
+ // 🟢 The same with prestations-ng, at any depth: the objects along the path are copied,
871
+ // the path is checked by TypeScript, and the signal notifies only when the value changes
872
+ ObjectPathHelper.patchSignal(this.address, ['locality', 'name'], 'newName');
869
873
  ```
870
874
 
871
875
  #### 8b. Two-way binding directly on an array element inside `@for`
@@ -879,12 +883,12 @@ two-way expression.
879
883
 
880
884
  ```html
881
885
  <!-- 🔴 Tries to write through model()[i] — mutates in place, breaks reactivity -->
882
- @for (item of model(); track item.id; let i = $index) {
886
+ @for (item of model(); track $index; let i = $index) {
883
887
  <app-address-row [(model)]="model()[i]" />
884
888
  }
885
889
 
886
890
  <!-- 🟢 One-way in, explicit handler out -->
887
- @for (item of model(); track item.id; let i = $index) {
891
+ @for (item of model(); track $index; let i = $index) {
888
892
  <app-address-row [model]="model()[i]" (modelChange)="updateItem(i, $event)" />
889
893
  }
890
894
  ```