@dsivd/prestations-ng 19.2.0-beta.26 → 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.
- package/AI_GUIDELINES.md +122 -0
- package/CHANGELOG.md +6 -0
- package/README.md +4 -0
- package/package.json +1 -1
package/AI_GUIDELINES.md
ADDED
|
@@ -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
|
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).
|
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.
|
|
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": {
|