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

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.
@@ -0,0 +1,122 @@
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, e.g. in the `.claude/CLAUDE.md` of your repository (the path is relative to the file holding the import):
6
+
7
+ ```text
8
+ @../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
9
+ ```
10
+
11
+ The explanations and the examples are in `GOOD_PRACTICES.md` and `UPGRADING_V19.md`, next to this file.
12
+
13
+ ## Check the project first
14
+
15
+ The strict mode and the zoneless change detection are optional steps of the migration to v19: check them before
16
+ applying the rules marked _strict_ or _zoneless_. The other rules apply to every project.
17
+
18
+ - Strict: `"strict": true` in the `compilerOptions` of `tsconfig.json` (and `"strictTemplates": true` in its
19
+ `angularCompilerOptions`).
20
+ - Zoneless: `provideZonelessChangeDetection()` in the providers of the application, and no `zone.js` in the
21
+ `polyfills` of `angular.json`. Without zone.js, Angular refreshes a view only when a signal read by its template
22
+ changes, or when it's notified: the rules marked _zoneless_ are required. With zone.js, they're the way to write
23
+ new code, but the existing code works without them: change it only when asked (see "Zoneless" and "Strict mode" in
24
+ `UPGRADING_V19.md`).
25
+
26
+ ## The form of a page
27
+
28
+ - `AbstractPageComponent` replaces the form with the JSON of the backend as is: at runtime, a field has the type of
29
+ the Java model, whatever its TypeScript type says. When the backend is in the repository, check the Java type of a
30
+ field before writing code that reads it.
31
+ - `form` and `reference` are `WritableSignal`s: read `form()` and `reference()`. Write a field of the form with
32
+ `patchForm(path, value)` (a typed path, e.g. `['children', $index, 'firstName']`), the whole form with `form.set()`
33
+ or `form.update()` and a new object. Never modify the form in place, and no `markForCheck()` after a write.
34
+ - 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.
40
+ Detail pages: `getListPath()`, `list()`, `itemToEdit()`, and `patchItem()`, `updateItem()` or `setItem()`.
41
+ - The `modelChange` of a `foehn-*` component is emitted only when the component writes its model (an input of the
42
+ user, a correction), never when the page changes it (form loaded, prefill, reset). React to the loaded form where
43
+ the page writes it, e.g. `GesdemEventService.formInitializationObservable()`.
44
+ - `reference()` is `undefined` until a form is loaded, `null` for a demand without reference: derive from it with
45
+ `computed()`. A request needing it is an `httpResource()` (or an `rxResource()` over a service) whose request
46
+ returns `undefined` while the reference is missing; read its `value()` only behind `hasValue()`.
47
+
48
+ ## The types of the fields
49
+
50
+ - The model of `foehn-input-number` is a `string` (`'0'` after an input), but the Java field is a number: once the
51
+ form comes back from the backend, it holds `0`. Same for any `string` model bound to a Java field which isn't a
52
+ `String`. Never test such a field by its truthiness (`!!x`, `if (x)`, `x || y`): compare it with `null` and `''`,
53
+ and convert it with `Number()` for a calculation.
54
+ - The values of the elements of `foehn-select` and `foehn-checkbox` have the type of the Java field: they are
55
+ compared to the model with `===` (`'1'` doesn't select `1`).
56
+ - A date is a `FoehnDateModel | null` (`[year, month, day]`, `LenientLocalDate` in Java), a date-time a
57
+ `FoehnDateTimeModel | null` (`[year, month, day, hour, minute]`, `LenientLocalDateTime`), a time a `string`
58
+ (`String` with `@ValidStringTime`). A part not entered is `null`, also once saved: never build a `Date` from it by
59
+ hand, use `DateHelper` and the `displayDate` pipe. See "Types of the form fields" in `GOOD_PRACTICES.md`.
60
+ - _Strict:_ a field the backend can omit or send as `null` is `T | null`, initialized with `null`, not `T` with a
61
+ `!`.
62
+
63
+ ## A component extending `FoehnInputComponent`
64
+
65
+ - Its model is a signal, which ignores the same reference: give `updateNgModel()` a new object or array, never the
66
+ model modified in place, or the page isn't notified. The inherited inputs are signals too: `this.name()`.
67
+ - A list reads its `model()` directly, binds its items with `[model]="item" (modelChange)="patchNgModel([i], $event)"`
68
+ and adds or removes one with a new array. Every change of a child reaches it through `modelChange`, not only
69
+ `userInput`.
70
+ - A component editing an object as is reads `model()` and writes a field with
71
+ `[model]="model()?.x" (modelChange)="patchNgModel(['x'], $event)"`. It overrides `emptyModel()`, after its public
72
+ members, when the page can give no object. Several fields at once:
73
+ `updateNgModel(Object.assign(new X(), this.model(), { a, b }))` (a spread loses the class). A rule applied at each
74
+ write, or `null` for an emptied object once `model_` is known: an override of `updateNgModel()` giving `super` the
75
+ corrected object. See "Editing an object field by field" in `GOOD_PRACTICES.md`.
76
+ - A component wrapping a single `foehn-*` component binds it with `[model]="model()"` and
77
+ `(modelChange)="updateNgModel($event)"`, never `[(model)]="model"`. See "Wrapping a single component".
78
+ - Only a component transforming its model (a date in three fields) has a `linkedSignal()` per field, derived from
79
+ `this.model`; when a field must keep its value on a partial model, use
80
+ `{ source: this.model, computation: (value, previous) => ... }`. No `onModelChange()` override copying the model.
81
+
82
+ ## Signals
83
+
84
+ - Derived state: a `computed()`, or a `linkedSignal()` when it can also be changed locally; never a signal kept in
85
+ sync from `ngOnChanges()`, an `effect()` or a `setTimeout()`.
86
+ - A method or a getter deriving a value only from signals becomes a `computed()` of the same name (a getter gains
87
+ `()`), and so does a method all of whose calls give it the same value read from a signal (the `computed()` reads
88
+ that signal itself). Only when everything it reads is a signal: a plain field, a service state that isn't a signal
89
+ or the DOM would leave it stale. Keep a method when its calls give it different values (e.g. the new value in a
90
+ `(userInput)` handler, the variable of a `@for`), has side effects, is overridden or implements a contract.
91
+ - Never modify in place a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new
92
+ 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.
95
+ - _Zoneless:_ a state read by a template and written by the code is a `signal()`, whoever writes it (a
96
+ `subscribe()`, a promise, a timer, a hook, a method called by a listener). Act on the rendered DOM (focus, scroll)
97
+ with `afterNextRender(..., { injector })`, never with `setTimeout()` or `NgZone`. `markForCheck()` only for a state
98
+ that can't be a signal. `effect()` as a last resort, with `untracked()`. See "Zoneless application" in
99
+ `GOOD_PRACTICES.md`.
100
+ - Before changing existing code, ask whether it would be written this way today: `setTimeout()`, `NgZone`,
101
+ `ngOnChanges()` and copies made "for the change detection" are often zone.js leftovers.
102
+
103
+ ## TypeScript
104
+
105
+ - Never silence the compiler or the linter: no `any`, `as any`, `as unknown as X`, `@ts-ignore`, `eslint-disable`.
106
+ - _Strict:_ a non-null assertion `!` only when the invariant is guaranteed and visible right there; otherwise narrow
107
+ (`if`, early return, `??`, `?.`) or fix the type where the value comes from.
108
+ - Remove a method override only calling the parent method with the same arguments, and a constructor only calling
109
+ `super()` (reported by `@typescript-eslint/no-useless-constructor`; see "A constructor only calling `super()`" in
110
+ `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.
112
+ - The rules of the ESLint plugin of the library (`no-direct-signal-mutation`, `require-model-change`,
113
+ `no-item-track-in-form-list`...) report the mistakes above: fix the code, don't turn them off.
114
+
115
+ ## Tests
116
+
117
+ - No `expect()` inside a `subscribe()`: `const value = firstValueFrom(obs$)` before triggering, then `await value`.
118
+ No `await` inside `expect()`.
119
+ - _Zoneless:_ `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` need zone.js. Answer the HTTP requests with
120
+ `HttpTestingController`, then `await fixture.whenStable()`; with Vitest, `vi.useFakeTimers()` and
121
+ `await vi.advanceTimersByTimeAsync(ms)` for the timers. A test changing the state of a component uses signals, as
122
+ the components do. See "Testing a zoneless component" in `GOOD_PRACTICES.md`.
package/CHANGELOG.md CHANGED
@@ -10,6 +10,12 @@
10
10
 
11
11
  ### Added
12
12
 
13
+ - [AI_GUIDELINES.md](AI_GUIDELINES.md) (since 19.2.0-beta.27): the rules an AI assistant follows in a project using
14
+ the library (the form of a page, the types of the fields, the components extending `FoehnInputComponent`, signals,
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.
18
+
13
19
  - [object-path.helper.ts](projects/prestations-ng/src/helpers/object-path.helper.ts)
14
20
  - New `ObjectPathHelper`: reads and writes a value at a path of any object, without modifying it: a write copies
15
21
  the objects and arrays along the path (with their prototype), keeps the others as they are, and gives the object
@@ -192,6 +198,10 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
192
198
  only takes strings, numbers, booleans, `null`, `undefined`, `any` and `RegExp`: a signal not called
193
199
  (`` `api/${this.reference}` ``) or an object turned into text by its `toString()` is reported. See
194
200
  [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#the-typescript-counterpart).
201
+ - 🚨 ESLint: `configs.tsRecommended` enables `@typescript-eslint/no-useless-constructor` (since 19.2.0-beta.26). A
202
+ constructor only passing its parameters to `super()`, typically the `constructor() { super(); }` left once the
203
+ services are injected with `inject()`, is reported: remove it. See
204
+ [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#a-constructor-only-calling-super) for a parent with a `protected` constructor.
195
205
  - 🚨 `AbstractPageComponent`: `form` is now a signal (`WritableSignal<T | null | undefined>`). Read it with `form()`,
196
206
  never modify its value in place: write it with the new `patchForm(path, value)`
197
207
  (`[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`), `form.set()` or `form.update()`. A
package/ESLINT_PLUGIN.md CHANGED
@@ -62,9 +62,11 @@ here they bring:
62
62
  stylistic, `angular-eslint` recommended, and for templates its accessibility set;
63
63
  - the house style — naming and selector conventions, import ordering
64
64
  (`simple-import-sort`, `import-x`), rxjs conventions, the signal rules of
65
- `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`), and
65
+ `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`),
66
66
  `@typescript-eslint/restrict-template-expressions` (see
67
- [The TypeScript counterpart](#the-typescript-counterpart)).
67
+ [The TypeScript counterpart](#the-typescript-counterpart)), and
68
+ `@typescript-eslint/no-useless-constructor` (see
69
+ [A constructor only calling `super()`](#a-constructor-only-calling-super)).
68
70
 
69
71
  Use `tsRules` / `templateRules` instead when a project supplies its own style and only wants
70
72
  the rules of this library. They register the plugin and nothing else, so you keep control of
@@ -428,3 +430,18 @@ called is reported, as is an object turned into text by its `toString()`. With
428
430
  ```ts
429
431
  '@typescript-eslint/restrict-template-expressions': 'error',
430
432
  ```
433
+
434
+ ## A constructor only calling `super()`
435
+
436
+ `configs.tsRecommended` enables `@typescript-eslint/no-useless-constructor`: a constructor
437
+ which only passes its parameters to `super()` is reported, typically the
438
+ `constructor() { super(); }` left once the services are injected with `inject()`. Remove it:
439
+ the class inherits the constructor of its parent. A `protected` or `private` constructor is
440
+ not reported, nor one giving other arguments to its parent (`super(Type.SUBSIDY)`).
441
+
442
+ When the removal gives `Cannot assign a 'protected' constructor type to a 'public'
443
+ constructor type` (TS2322 on the `component` of a route, TS2345 on
444
+ `TestBed.createComponent()`), the parent declares a `protected constructor()`, which the
445
+ class now inherits. Remove that one too when the parent is `abstract`: it already can't be
446
+ instantiated. Otherwise keep the constructor of the class, with an `eslint-disable-next-line`
447
+ saying why.
package/README.md CHANGED
@@ -23,6 +23,10 @@ The documentation is available online at [https://dsi-vd.github.io/prestations-n
23
23
  The library also ships an ESLint plugin whose rules apply to your project: see
24
24
  [the plugin guide](ESLINT_PLUGIN.md).
25
25
 
26
+ An AI assistant working on your project (Claude Code, GitHub Copilot...) follows the rules of
27
+ [AI_GUIDELINES.md](AI_GUIDELINES.md), published with the library for the version you installed: import it into the
28
+ instructions of your assistant, as explained at the top of the file.
29
+
26
30
  Migration guides are available to provide an upgrade path from one major version to another.
27
31
 
28
32
  - If you need to upgrade to version `19+`, please refer to [the V19 upgrade guide](UPGRADING_V19.md).
@@ -92,6 +92,11 @@ const tsRecommended = (plugin) => [
92
92
  // off here — @typescript-eslint/no-shadow handles it correctly for TS
93
93
  'no-shadow': 'off',
94
94
  '@typescript-eslint/no-shadow': ['error', { hoist: 'all' }],
95
+ // a constructor only passing its parameters to super(), e.g. the
96
+ // `constructor() { super(); }` left once the services are injected with
97
+ // inject(); off here — the core rule ignores the parameter properties
98
+ 'no-useless-constructor': 'off',
99
+ '@typescript-eslint/no-useless-constructor': 'error',
95
100
  '@typescript-eslint/no-unused-vars': [
96
101
  'error',
97
102
  {
package/package.json CHANGED
@@ -39,7 +39,7 @@
39
39
  "ng-update": {
40
40
  "migrations": "./schematics/migration-collection.json"
41
41
  },
42
- "version": "19.2.0-beta.25",
42
+ "version": "19.2.0-beta.27",
43
43
  "module": "fesm2022/dsivd-prestations-ng.mjs",
44
44
  "typings": "types/dsivd-prestations-ng.d.ts",
45
45
  "exports": {
@@ -126,6 +126,21 @@ describe('eslint configs', () => {
126
126
  );
127
127
  });
128
128
 
129
+ describe('tsRecommended', () => {
130
+ // The last entry setting a rule wins, as in ESLint
131
+ const rules = Object.assign(
132
+ {},
133
+ ...configs.tsRecommended.map((entry) => entry.rules ?? {}),
134
+ );
135
+
136
+ it('should report a constructor only calling super() with the rule of typescript-eslint', () => {
137
+ expect(rules['@typescript-eslint/no-useless-constructor']).toBe(
138
+ 'error',
139
+ );
140
+ expect(rules['no-useless-constructor']).toBe('off');
141
+ });
142
+ });
143
+
129
144
  describe('specTsRecommended', () => {
130
145
  const rulesOf = (config) =>
131
146
  Object.assign({}, ...config.map((entry) => entry.rules ?? {}));
@@ -92,6 +92,11 @@ const tsRecommended = (plugin) => [
92
92
  // off here — @typescript-eslint/no-shadow handles it correctly for TS
93
93
  'no-shadow': 'off',
94
94
  '@typescript-eslint/no-shadow': ['error', { hoist: 'all' }],
95
+ // a constructor only passing its parameters to super(), e.g. the
96
+ // `constructor() { super(); }` left once the services are injected with
97
+ // inject(); off here — the core rule ignores the parameter properties
98
+ 'no-useless-constructor': 'off',
99
+ '@typescript-eslint/no-useless-constructor': 'error',
95
100
  '@typescript-eslint/no-unused-vars': [
96
101
  'error',
97
102
  {