@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.
- package/AI_GUIDELINES.md +152 -0
- package/ANGULAR_SIGNALS.md +6 -2
- package/CHANGELOG.md +476 -0
- package/CONTRIBUTING.md +128 -8
- package/ESLINT_PLUGIN.md +262 -30
- package/GOOD_PRACTICES.md +983 -388
- package/INTRODUCTION_ANGULAR_SIGNALS.md +227 -155
- package/README.md +22 -12
- package/UPGRADING_V18.md +5 -5
- package/UPGRADING_V19.md +636 -19
- package/eslint/configs/spec-ts-recommended.mjs +34 -0
- package/eslint/configs/template-recommended.mjs +2 -0
- package/eslint/configs/template-rules.mjs +14 -2
- package/eslint/configs/ts-recommended.mjs +11 -0
- package/eslint/configs/ts-rules.mjs +6 -2
- package/eslint/form-reads.mjs +63 -0
- package/eslint/index.mjs +17 -0
- package/eslint/rules/index.mjs +6 -0
- package/eslint/rules/no-direct-signal-mutation.mjs +162 -41
- package/eslint/rules/no-item-track-in-form-list.mjs +173 -0
- package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/eslint/rules/require-model-change.mjs +89 -0
- package/eslint/rules/require-track-index.mjs +162 -0
- package/eslint/signal-names.mjs +127 -21
- package/eslint/template-ast.mjs +12 -2
- package/fesm2022/dsivd-prestations-ng.mjs +2889 -2061
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -2
- package/schematics/migration-collection.json +5 -0
- package/schematics/ng-add/index.js +2 -4
- package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
- package/schematics/ng-update/migrations/update-19_2_0/index.js +52 -0
- package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
- package/schematics/utility/form-signal/class-migration.js +795 -0
- package/schematics/utility/form-signal/edits.js +34 -0
- package/schematics/utility/form-signal/form-members.js +318 -0
- package/schematics/utility/form-signal/form-signal-migration.js +134 -0
- package/schematics/utility/form-signal/page-classes.js +139 -0
- package/schematics/utility/form-signal/template-migration.js +775 -0
- package/schematics/utility/never-connected-migration.js +87 -0
- package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
- package/schematics/utility/typescript-files.js +95 -0
- package/src/eslint/configs/__tests__/configs.test.mjs +61 -2
- package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
- package/src/eslint/configs/template-recommended.mjs +2 -0
- package/src/eslint/configs/template-rules.mjs +14 -2
- package/src/eslint/configs/ts-recommended.mjs +11 -0
- package/src/eslint/configs/ts-rules.mjs +6 -2
- package/src/eslint/form-reads.mjs +63 -0
- package/src/eslint/index.mjs +17 -0
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +200 -0
- package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
- package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
- package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
- package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
- package/src/eslint/rules/index.mjs +6 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +162 -41
- package/src/eslint/rules/no-item-track-in-form-list.mjs +173 -0
- package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/src/eslint/rules/require-model-change.mjs +89 -0
- package/src/eslint/rules/require-track-index.mjs +162 -0
- package/src/eslint/signal-names.mjs +127 -21
- package/src/eslint/template-ast.mjs +12 -2
- package/types/dsivd-prestations-ng.d.ts +719 -243
- package/dsivd-prestations-ng-19.2.0-beta.3.tgz +0 -0
package/AI_GUIDELINES.md
ADDED
|
@@ -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()`.
|
package/ANGULAR_SIGNALS.md
CHANGED
|
@@ -866,6 +866,10 @@ this.address.update((current) => ({
|
|
|
866
866
|
...current,
|
|
867
867
|
locality: { ...current.locality, name: 'newName' },
|
|
868
868
|
}));
|
|
869
|
+
|
|
870
|
+
// 🟢 The same with prestations-ng, at any depth: the objects along the path are copied,
|
|
871
|
+
// the path is checked by TypeScript, and the signal notifies only when the value changes
|
|
872
|
+
ObjectPathHelper.patchSignal(this.address, ['locality', 'name'], 'newName');
|
|
869
873
|
```
|
|
870
874
|
|
|
871
875
|
#### 8b. Two-way binding directly on an array element inside `@for`
|
|
@@ -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
|
|
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
|
|
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
|
```
|