@dsivd/prestations-ng 19.2.0-beta.20 â 19.2.0-beta.21
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/ANGULAR_SIGNALS.md +4 -0
- package/CHANGELOG.md +98 -3
- package/CONTRIBUTING.md +2 -2
- package/ESLINT_PLUGIN.md +103 -8
- package/GOOD_PRACTICES.md +79 -29
- package/UPGRADING_V19.md +187 -31
- package/eslint/configs/template-rules.mjs +5 -0
- package/eslint/configs/ts-recommended.mjs +4 -0
- package/eslint/form-reads.mjs +63 -0
- package/eslint/rules/index.mjs +4 -0
- package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
- package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
- package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/eslint/rules/require-model-change.mjs +89 -0
- package/eslint/template-ast.mjs +12 -2
- package/fesm2022/dsivd-prestations-ng.mjs +907 -692
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -1
- package/schematics/migration-collection.json +5 -0
- package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
- package/schematics/utility/form-signal/class-migration.js +396 -0
- package/schematics/utility/form-signal/edits.js +34 -0
- package/schematics/utility/form-signal/form-signal-migration.js +184 -0
- package/schematics/utility/form-signal/page-classes.js +129 -0
- package/schematics/utility/form-signal/template-migration.js +666 -0
- package/src/eslint/configs/template-rules.mjs +5 -0
- package/src/eslint/configs/ts-recommended.mjs +4 -0
- package/src/eslint/form-reads.mjs +63 -0
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
- package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -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/index.mjs +4 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
- package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -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/template-ast.mjs +12 -2
- package/types/dsivd-prestations-ng.d.ts +234 -35
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`
|
package/CHANGELOG.md
CHANGED
|
@@ -10,10 +10,43 @@
|
|
|
10
10
|
|
|
11
11
|
### Added
|
|
12
12
|
|
|
13
|
+
- [object-path.helper.ts](projects/prestations-ng/src/helpers/object-path.helper.ts)
|
|
14
|
+
- New `ObjectPathHelper`: reads and writes a value at a path of any object, without modifying it: a write copies
|
|
15
|
+
the objects and arrays along the path (with their prototype), keeps the others as they are, and gives the object
|
|
16
|
+
itself when the value is already there.
|
|
17
|
+
- `get(object, path)`, `patch(object, path, value)` and `patchSignal(signal, path, value)` (for a signal holding
|
|
18
|
+
an object: its readers are notified only when the value changes) take a path checked by TypeScript, typed with
|
|
19
|
+
the new `ObjectPath<T>` (`['address', 'street']`, `['children', 0, 'firstName']`, the paths of each member of a
|
|
20
|
+
union) and `ObjectPathValue<T, P>`.
|
|
21
|
+
- `getByKeys(object, keys)` and `patchByKeys(object, keys, value)` take keys known at runtime only
|
|
22
|
+
(`'address.street'`, or a list of keys), not checked.
|
|
23
|
+
- `patchForm()`, `patchItem()`, `PendingUploadService`, the custom errors of the street of `foehn-input-address`
|
|
24
|
+
and the elements of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes use it.
|
|
25
|
+
- `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
|
|
26
|
+
classes and their templates (see the đ¨ entries below and
|
|
27
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
|
|
28
|
+
migrate, and running it again changes nothing.
|
|
29
|
+
- đ¨ ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
|
|
30
|
+
[`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
|
|
31
|
+
`configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
|
|
32
|
+
is lost; a component always disabled, `foehn-input-hidden`, `foehn-table` and a component listening to
|
|
33
|
+
`(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
|
|
34
|
+
at every input).
|
|
35
|
+
|
|
13
36
|
- [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
|
|
14
37
|
- New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
|
|
15
38
|
`LenientLocalDate` of prestations-be), to type the date fields of your forms, e.g.
|
|
16
39
|
`birthDate: FoehnDateModel | null = null;`.
|
|
40
|
+
- `DateHelper.isValid()`, `isToday()` and `toDayjsFromNumberArray()` accept it, `null` and `undefined`
|
|
41
|
+
included: no cast in a strict project. A date with a part not entered is still neither valid nor today, and
|
|
42
|
+
gives `null`.
|
|
43
|
+
- [foehn-date-time-model.type.ts](projects/prestations-ng/src/foehn-input-date-time/foehn-date-time-model.type.ts)
|
|
44
|
+
- New `FoehnDateTimeModel` type, the model of `foehn-input-date-time` (`(number | null)[]`: year, month, day,
|
|
45
|
+
hour, minute, the JSON of a `LenientLocalDateTime` of prestations-be).
|
|
46
|
+
- The `displayDate` pipe, `DateHelper.toDateFromNumberArray()`, `arrayToDisplayDateDMY()`, `isValid()` and
|
|
47
|
+
`isToday()` accept it, as well as a `FoehnDateModel`. The new `DateHelper.hasTime()` tells whether a date-time
|
|
48
|
+
has its time entered.
|
|
49
|
+
`DateHelper.leftPad()` accepts `null` and `undefined` (it already returned `''`).
|
|
17
50
|
- [eslint/configs/spec-ts-recommended.mjs](projects/prestations-ng/src/eslint/configs/spec-ts-recommended.mjs)
|
|
18
51
|
- New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
|
|
19
52
|
`**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
|
|
@@ -143,6 +176,31 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
143
176
|
- `epayment-form` (`SdkEpaymentComponent`): `failureModalDisplayed`, `redirectModalDisplayed`
|
|
144
177
|
- `captcha` (`SdkRecaptchaComponent`): `isLoaded`, `hasLoadingError`
|
|
145
178
|
- `redirector` (`RedirectComponent`): `counter`
|
|
179
|
+
- đ¨ `AbstractPageComponent`: `reference` is now a signal. Read it with `reference()` in your pages and their
|
|
180
|
+
templates, and write it with `reference.set()`. A template, a `computed()` or an `effect()` reading it follows the
|
|
181
|
+
reference, also when your page sets it, without `markForCheck()`. A page declaring its own `reference` field no
|
|
182
|
+
longer compiles: remove it. The `ng update` migration rewrites your pages, see
|
|
183
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#reference-of-your-pages-is-a-signal-since-1920).
|
|
184
|
+
- đ¨ ESLint: `configs.tsRecommended` enables `@typescript-eslint/restrict-template-expressions`. A template literal
|
|
185
|
+
only takes strings, numbers, booleans, `null`, `undefined`, `any` and `RegExp`: a signal not called
|
|
186
|
+
(`` `api/${this.reference}` ``) or an object turned into text by its `toString()` is reported. See
|
|
187
|
+
[ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#the-typescript-counterpart).
|
|
188
|
+
- đ¨ `AbstractPageComponent`: `form` is now a signal (`WritableSignal<T | null | undefined>`). Read it with `form()`,
|
|
189
|
+
never modify its value in place: write it with the new `patchForm(path, value)`
|
|
190
|
+
(`[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`), `form.set()` or `form.update()`. A
|
|
191
|
+
template, a `computed()` or an `effect()` reading it follows every input of the user, and no `markForCheck()` is
|
|
192
|
+
needed after a write anymore. The `ng update` migration rewrites your pages, see
|
|
193
|
+
[UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920).
|
|
194
|
+
- đ¨ `AbstractListDetailPageComponent`: the abstract `getListPath()` (the path of the list in the form) replaces the
|
|
195
|
+
abstract `getList()`, which reads the list at that path. `list`, `itemIndex` and `itemToEdit` are now signals. The
|
|
196
|
+
item edited is written with the new `patchItem(path, value)`, `updateItem(update)` (several fields in one write)
|
|
197
|
+
and `setItem(item)`. A new item is added without modifying the list of the form in place.
|
|
198
|
+
- `PendingUploadService` writes the documents uploaded with the form into a new form, instead of modifying the form
|
|
199
|
+
in place.
|
|
200
|
+
- đ¨ ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) sees through the
|
|
201
|
+
TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
|
|
202
|
+
now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
|
|
203
|
+
`[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
|
|
146
204
|
- The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
|
|
147
205
|
`foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
|
|
148
206
|
`foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
|
|
@@ -163,6 +221,14 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
163
221
|
now documented in
|
|
164
222
|
[UPGRADING_V19.md](UPGRADING_V19.md#modelchange-is-emitted-only-when-the-component-writes-its-model), and on the
|
|
165
223
|
Lifecycle page of the documentation, which said the opposite.
|
|
224
|
+
- đ¨ The `onModelChange()` methods which were not the hook of `FoehnInputComponent` are removed or renamed (they are
|
|
225
|
+
not called by the model anymore):
|
|
226
|
+
- `foehn-date-picker-button`: `model_`, `onModelChange()` and `updateNgModel()` are removed, they had no effect
|
|
227
|
+
(`model_` was never read).
|
|
228
|
+
- `foehn-date-picker`: `model_` is removed (never read), `onModelChange()` is now private (`syncWithModel()`).
|
|
229
|
+
- `numberCurrencyFormatter`: `onModelChange()` is now private (`formatModel()`), and the directive no longer
|
|
230
|
+
listens to the `modelChange` of its host: its `effect()` already formats every model, the ones written by the
|
|
231
|
+
host were formatted twice.
|
|
166
232
|
- `SdkDictionaryService.getKeySync()` reads a signal: a `computed()` or a template calling it is refreshed
|
|
167
233
|
when the dictionary is (re)loaded, e.g. when the language changes.
|
|
168
234
|
- `foehn-autocomplete` and `foehn-multiselect-autocomplete`: the value to display, its reset, the default
|
|
@@ -183,9 +249,28 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
183
249
|
|
|
184
250
|
- `AbstractMenuPageComponent.ngZone` is no longer used and will be removed: `NgZone.onStable` never emits
|
|
185
251
|
without zone.js.
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
252
|
+
- `ObjectHelper.getNestedProperty(obj, key)` will be removed: use `ObjectPathHelper.getByKeys(obj, key)`, which it
|
|
253
|
+
now calls (see Fixed).
|
|
254
|
+
|
|
255
|
+
### Fixed
|
|
256
|
+
|
|
257
|
+
- đ¨ `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
|
|
258
|
+
`elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
|
|
259
|
+
autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
|
|
260
|
+
a class, is no longer `undefined`, and a nested key is no longer looked up in another nested object holding the same
|
|
261
|
+
key (`'country.name'` gave the `name` of the first nested object having one). A value `null` is no longer
|
|
262
|
+
`undefined` either: an element `{ value: null }` is now selected by a model `null` (e.g. sent by the backend), no
|
|
263
|
+
longer by a model `undefined` (e.g. a field missing from the JSON), and choosing it writes `null` into the model, no
|
|
264
|
+
longer `undefined`.
|
|
265
|
+
- đ¨ `DateHelper.isValid()` also checks the time of a date-time (5 parts or more, e.g. the model of
|
|
266
|
+
`foehn-input-date-time`), as `LenientLocalDateTime.isValid()` of prestations-be: an hour (0 to 23) and a minute (0
|
|
267
|
+
to 59) are required. It only checked the date: a date-time without its time, or at 25:00, was valid. Check your
|
|
268
|
+
calls on a date-time. `isToday()` still considers only the date.
|
|
269
|
+
- The `displayDate` pipe, `DateHelper.toDateFromNumberArray()` and `arrayToDisplayDateDMY()` no longer give a wrong
|
|
270
|
+
date for a date with a part not entered (e.g. a draft saved with an incomplete date): `[2020, null, null]` was
|
|
271
|
+
displayed `30.11.2019`, it now gives nothing. A date-time without its time gives only the date (it displayed
|
|
272
|
+
`00:00:00`), and an empty array gives nothing (it threw an error). `DateHelper.isToday()`: a date which does not
|
|
273
|
+
exist is no longer today (the 30.02.2026 was the 02.03.2026).
|
|
189
274
|
- `AbstractPageComponent` and `AbstractPageFromMenuComponent`: a second click on "next" or "transmit" while the next
|
|
190
275
|
page is loading (lazy loaded route, resolver, async guard) no longer saves again and skips the next page:
|
|
191
276
|
`send()`, `sendAndTransmit()` and `transmit()` are ignored until the navigation to the next page ends. Pages
|
|
@@ -226,6 +311,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
226
311
|
component (e.g. prefilled with `SessionInfoWithApplicationService.prefillForm()` for a connected user) is no
|
|
227
312
|
longer overwritten by the model with the default country only; the default country and the clean-up of the model
|
|
228
313
|
are applied after the next rendering, from the latest model.
|
|
314
|
+
- `foehn-input-address` in Switzerland only (`isOnlySwiss`): an address given by the page without country after the
|
|
315
|
+
initialization of the component (e.g. a form loaded from the backend) gets the Swiss country again, as in v18: it
|
|
316
|
+
kept `country: null` until the user changed a field. The default country is checked again for every model given by
|
|
317
|
+
the page, and written only when it changes the model: an identical model is no longer written back (one
|
|
318
|
+
`modelChange` less), and an address without any value to display is left as it is.
|
|
229
319
|
- `foehn-input-address`: the streets and the street numbers of an address given by the page are loaded again, as in
|
|
230
320
|
v18. Since 19.0.0, they were only loaded once the user chose a locality and a street (the autocompletes no longer
|
|
231
321
|
emit `modelChange` for a model given by the page), and a locality given with its `zipCodeId` only (without
|
|
@@ -295,6 +385,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
295
385
|
- `foehn-feedback-notification`: an error of `api/feedbacknotification/queryparams/{reference}` is logged and the
|
|
296
386
|
links are displayed without the feedback url, it reached the `ErrorHandler` as unhandled.
|
|
297
387
|
- The npm package no longer contains its own archive (`dsivd-prestations-ng-<version>.tgz`).
|
|
388
|
+
- ESLint rules [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) and
|
|
389
|
+
[`no-uninvoked-signal-in-template`](ESLINT_PLUGIN.md#no-uninvoked-signal-in-template): an explicit `(xChange)`
|
|
390
|
+
handler is no longer taken for the target of a two-way binding `[(x)]`. `no-direct-signal-mutation` reported
|
|
391
|
+
`(modelChange)="updateModel()"` in a template shared by several components (its component file not found), and
|
|
392
|
+
`no-uninvoked-signal-in-template` let `(valueChange)="mySignal"` through.
|
|
298
393
|
|
|
299
394
|
## [19.1.1]
|
|
300
395
|
|
package/CONTRIBUTING.md
CHANGED
|
@@ -236,8 +236,8 @@ mechanism inherited from zone.js:
|
|
|
236
236
|
object. No copy is then needed "so that the change detection sees a new reference".
|
|
237
237
|
- Asynchronous work: set a signal in the callback, or convert the `Observable` with `toSignal()` where it is
|
|
238
238
|
displayed. The services keep returning `Observable`s.
|
|
239
|
-
- `markForCheck()` only for a state that can't be a signal (e.g. the
|
|
240
|
-
the
|
|
239
|
+
- `markForCheck()` only for a state that can't be a signal (e.g. the plain fields that the pages of the projects set
|
|
240
|
+
when their form is loaded: `AbstractPageComponent` marks the page then).
|
|
241
241
|
- Act on the rendered DOM (focus, scroll, measure) with `afterNextRender(..., { injector })`, never with
|
|
242
242
|
`setTimeout()` or `NgZone`.
|
|
243
243
|
- `effect()` as a last resort, with `untracked()` for what isn't a trigger. Never use it to copy a signal into another
|
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` |
|
|
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` |
|
|
57
57
|
|
|
58
58
|
The `*Recommended` presets are what a project normally extends. On top of the rules written
|
|
59
59
|
here they bring:
|
|
@@ -61,8 +61,10 @@ here they bring:
|
|
|
61
61
|
- the baselines â `eslint.configs.recommended`, `typescript-eslint` recommended and
|
|
62
62
|
stylistic, `angular-eslint` recommended, and for templates its accessibility set;
|
|
63
63
|
- the house style â naming and selector conventions, import ordering
|
|
64
|
-
(`simple-import-sort`, `import-x`), rxjs conventions,
|
|
65
|
-
`angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`)
|
|
64
|
+
(`simple-import-sort`, `import-x`), rxjs conventions, the signal rules of
|
|
65
|
+
`angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`), and
|
|
66
|
+
`@typescript-eslint/restrict-template-expressions` (see
|
|
67
|
+
[The TypeScript counterpart](#the-typescript-counterpart)).
|
|
66
68
|
|
|
67
69
|
Use `tsRules` / `templateRules` instead when a project supplies its own style and only wants
|
|
68
70
|
the rules of this library. They register the plugin and nothing else, so you keep control of
|
|
@@ -110,6 +112,7 @@ this.model().items.splice(index, 1);
|
|
|
110
112
|
|
|
111
113
|
// â
|
|
112
114
|
this.model.update((current) => ({ ...current, property: value }));
|
|
115
|
+
ObjectPathHelper.patchSignal(this.model, ['deep', 'property'], value); // at any depth
|
|
113
116
|
this.model.update((current) => ({
|
|
114
117
|
...current,
|
|
115
118
|
items: current.items.filter((_, i) => i !== index),
|
|
@@ -143,6 +146,10 @@ delete this.model().users[0];
|
|
|
143
146
|
Object.assign(this.model(), { property: value });
|
|
144
147
|
```
|
|
145
148
|
|
|
149
|
+
The TypeScript wrappers which keep the value are seen through: `this.form()!.name = value`
|
|
150
|
+
and `(this.model() as Model).name = value` are reported as well, as are, in a template,
|
|
151
|
+
`[(ngModel)]="form()!.name"` and `(form()).name = value`.
|
|
152
|
+
|
|
146
153
|
#### Names bound to the value
|
|
147
154
|
|
|
148
155
|
A mutation is rarely written on the signal read itself. The rule follows the value through
|
|
@@ -164,6 +171,11 @@ this.model().users.forEach((user) => (user.done = true));
|
|
|
164
171
|
<button (click)="user.tags.push(tag)">âĻ</button>
|
|
165
172
|
}
|
|
166
173
|
|
|
174
|
+
<!-- â the alias of an @if, bound only inside its own branch -->
|
|
175
|
+
@if (form(); as form) {
|
|
176
|
+
<foehn-input-text name="name" [(model)]="form.name" />
|
|
177
|
+
}
|
|
178
|
+
|
|
167
179
|
<!-- â a @let -->
|
|
168
180
|
@let users = model().users;
|
|
169
181
|
<button (click)="users.push(user)">âĻ</button>
|
|
@@ -295,6 +307,77 @@ found without declaring anything.
|
|
|
295
307
|
| `[(value)]="mySignal"` | a writable signal is two-way bound **without** parentheses, Angular calls `.set()` itself |
|
|
296
308
|
| `#ref`, `@for` items, `@if âĻ as`, `@let`, `let-x`, `$index`âĻ | template-local names shadow the class members |
|
|
297
309
|
|
|
310
|
+
### `require-model-change`
|
|
311
|
+
|
|
312
|
+
Reports a `foehn-*` component given a field of the form of the page with a one-way `[model]`
|
|
313
|
+
and no `(modelChange)`. The component changes its own model only: what the user enters never
|
|
314
|
+
reaches the form, and is lost when the form is saved.
|
|
315
|
+
|
|
316
|
+
Applies to **templates only**.
|
|
317
|
+
|
|
318
|
+
```html
|
|
319
|
+
<!-- â the input of the user is lost -->
|
|
320
|
+
<foehn-input-text [model]="form.firstName" />
|
|
321
|
+
|
|
322
|
+
<!-- â -->
|
|
323
|
+
<foehn-input-text
|
|
324
|
+
[model]="form.firstName"
|
|
325
|
+
(modelChange)="patchForm(['firstName'], $event)"
|
|
326
|
+
/>
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Only the models read from the form are checked: `form()`, `form.firstName`, and the names
|
|
330
|
+
bound to it by `@if (form(); as form)`, `@let form = this.form()` or
|
|
331
|
+
`@for (child of form.children; âĻ)`. A one-way `[model]` is legitimate elsewhere (a table
|
|
332
|
+
displaying a list, a menu...). `[(model)]` declares both bindings and is never reported.
|
|
333
|
+
|
|
334
|
+
Not reported either, as the input of the user can't be lost:
|
|
335
|
+
|
|
336
|
+
- a component always disabled, `disabled="true"` or `[disabled]="true"` (a disabled component
|
|
337
|
+
doesn't write its model), unless it is given `updateModelWhenDisabled`;
|
|
338
|
+
- `foehn-input-hidden` and `foehn-table`, which never write their model;
|
|
339
|
+
- a component listening to `(userInput)`, whose handler writes the form.
|
|
340
|
+
|
|
341
|
+
A `[disabled]` depending on a condition is reported: once the component is enabled, the input of
|
|
342
|
+
the user would be lost. A bare `disabled` is reported too: it gives `''`, which doesn't disable
|
|
343
|
+
the component.
|
|
344
|
+
|
|
345
|
+
```html
|
|
346
|
+
<!-- â displayed only -->
|
|
347
|
+
<foehn-input-text [model]="form.reference" [disabled]="true" />
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
### `no-item-track-in-form-list`
|
|
351
|
+
|
|
352
|
+
Reports a `@for` over a list of the form whose rows edit their item, tracked by the item
|
|
353
|
+
itself (`track child`, `track $any(child)`). Writing a field of an item with `patchForm()`
|
|
354
|
+
or `patchItem()` replaces the item with a copy: its row is destroyed and created again at
|
|
355
|
+
every input, and the field being edited loses the focus.
|
|
356
|
+
|
|
357
|
+
Applies to **templates only**.
|
|
358
|
+
|
|
359
|
+
```html
|
|
360
|
+
<!-- â the field loses the focus at every input -->
|
|
361
|
+
@for (child of form.children; track child) {
|
|
362
|
+
<foehn-input-text
|
|
363
|
+
[model]="child.firstName"
|
|
364
|
+
(modelChange)="patchForm(['children', $index, 'firstName'], $event)"
|
|
365
|
+
/>
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
<!-- â -->
|
|
369
|
+
@for (child of form.children; track child.id) { âĻ } @for (child of
|
|
370
|
+
form.children; track $index) { âĻ }
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
A row edits its item when one of its elements has a `model` read from it
|
|
374
|
+
(`[model]="child.firstName"`, `[(model)]="child"`). A list only displayed, or not read from
|
|
375
|
+
the form, is left alone. The rule suggests `track $index` (an identifier of the item is
|
|
376
|
+
often better: it keeps the row of an item when the list is reordered).
|
|
377
|
+
|
|
378
|
+
> đĄ The control flow migration of Angular turns a `*ngFor` without `trackBy` into
|
|
379
|
+
> `track <item>`: after it, check the lists of the form.
|
|
380
|
+
|
|
298
381
|
## The TypeScript counterpart
|
|
299
382
|
|
|
300
383
|
`@angular-eslint/no-uncalled-signals` covers the same class of bug **in TypeScript**, using
|
|
@@ -310,3 +393,15 @@ are complementary, not redundant.
|
|
|
310
393
|
|
|
311
394
|
It only reports signals used in logic positions (`if`, `!x`, `&&`, `===`, `.length`âĻ), not a
|
|
312
395
|
bare `const x = mySignal`.
|
|
396
|
+
|
|
397
|
+
Nor a template literal: `` `api/${this.reference}/pdf-sections` `` compiles, and gives the
|
|
398
|
+
signal itself as text (`[Signal: âĻ]`, or the source of a function in production) instead of
|
|
399
|
+
its value. `configs.tsRecommended` also enables
|
|
400
|
+
`@typescript-eslint/restrict-template-expressions`, which only lets strings, numbers,
|
|
401
|
+
booleans, `null`, `undefined`, `any` and `RegExp` into a template literal: a signal not
|
|
402
|
+
called is reported, as is an object turned into text by its `toString()`. With
|
|
403
|
+
`configs.tsRules` you enable it yourself (it requires type information too):
|
|
404
|
+
|
|
405
|
+
```ts
|
|
406
|
+
'@typescript-eslint/restrict-template-expressions': 'error',
|
|
407
|
+
```
|
package/GOOD_PRACTICES.md
CHANGED
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
- [The `<fieldset>` and `<legend>` tags](good-practices#the__code__lt_fieldset_gt___code__and__code__lt_legend_gt___code__tags)
|
|
22
22
|
- [Screen reader (show / hide)](good-practices#screen_reader__show___hide_)
|
|
23
23
|
- [A prestations-ng page](good-practices#a_prestations-ng_page)
|
|
24
|
+
- [Binding the fields of the form](good-practices#binding_the_fields_of_the_form)
|
|
24
25
|
- [Zoneless application](good-practices#zoneless_application)
|
|
25
26
|
- [Displaying an asynchronous state](good-practices#displaying_an_asynchronous_state)
|
|
26
27
|
- [Deriving a state from view queries](good-practices#deriving_a_state_from_view_queries)
|
|
@@ -333,6 +334,7 @@ with text for visually impaired people.
|
|
|
333
334
|
5. The first heading tag of your page must be an h2 (`<h2>`)
|
|
334
335
|
6. Add `<foehn-navigation>`
|
|
335
336
|
7. If you have several pages, use the `<foehn-page-counter>` component
|
|
337
|
+
8. Bind the fields of the form with `[model]` and `(modelChange)="patchForm([...], $event)"` (see below)
|
|
336
338
|
|
|
337
339
|
`page-one.component.ts`
|
|
338
340
|
|
|
@@ -386,7 +388,15 @@ export class PageOneComponent
|
|
|
386
388
|
fromDictionary }}
|
|
387
389
|
</h2>
|
|
388
390
|
|
|
391
|
+
<!-- point (8) -->
|
|
392
|
+
@if (form(); as form) {
|
|
393
|
+
<foehn-input-text
|
|
394
|
+
name="firstName"
|
|
395
|
+
[model]="form.firstName"
|
|
396
|
+
(modelChange)="patchForm(['firstName'], $event)"
|
|
397
|
+
/>
|
|
389
398
|
<!-- [YOUR FOEHN COMPONENTS HERE] -->
|
|
399
|
+
}
|
|
390
400
|
|
|
391
401
|
<foehn-navigation
|
|
392
402
|
id="navigation"
|
|
@@ -400,6 +410,46 @@ export class PageOneComponent
|
|
|
400
410
|
</div>
|
|
401
411
|
```
|
|
402
412
|
|
|
413
|
+
### Binding the fields of the form
|
|
414
|
+
|
|
415
|
+
The `form` of a page is a signal: read it with `form()`, and never modify its value in place. Write a field with
|
|
416
|
+
`patchForm(path, value)`, which copies the objects along the path: the templates, the `computed()` and the
|
|
417
|
+
`effect()` reading the form follow every input of the user.
|
|
418
|
+
|
|
419
|
+
```html
|
|
420
|
+
@if (form(); as form) {
|
|
421
|
+
<foehn-input-text
|
|
422
|
+
name="address.street"
|
|
423
|
+
[model]="form.address.street"
|
|
424
|
+
(modelChange)="patchForm(['address', 'street'], $event)"
|
|
425
|
+
/>
|
|
426
|
+
@for (child of form.children; track child.id) {
|
|
427
|
+
<foehn-input-text
|
|
428
|
+
[name]="'children[' + $index + '].firstName'"
|
|
429
|
+
[model]="child.firstName"
|
|
430
|
+
(modelChange)="patchForm(['children', $index, 'firstName'], $event)"
|
|
431
|
+
/>
|
|
432
|
+
} }
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
```ts
|
|
436
|
+
readonly childrenCount = computed(() => this.form()?.children.length ?? 0);
|
|
437
|
+
|
|
438
|
+
addChild(): void {
|
|
439
|
+
this.patchForm(['children'], [...(this.form()?.children ?? []), new Child()]);
|
|
440
|
+
}
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
- The path is checked by TypeScript (a typo gives an error listing the valid keys).
|
|
444
|
+
- Never a `[model]` alone on a field the user can change: what the user enters would never reach the form
|
|
445
|
+
(`require-model-change` reports it). A field always disabled (`[disabled]="true"`), only displayed, is bound with
|
|
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).
|
|
450
|
+
- A detail page (`AbstractListDetailPageComponent`) gives the path of its list with `getListPath()`, and writes the
|
|
451
|
+
item edited with `patchItem()`, `updateItem()` or `setItem()`.
|
|
452
|
+
|
|
403
453
|
## Zoneless application
|
|
404
454
|
|
|
405
455
|
> âšī¸ Since v19.2, prestations-ng no longer needs zone.js and we recommend that you make your
|
|
@@ -459,32 +509,20 @@ modifies: the listener notifies Angular, but the same method can later be called
|
|
|
459
509
|
or an `effect()`, and the field would no longer be displayed. A signal notifies Angular whoever
|
|
460
510
|
modifies it.
|
|
461
511
|
|
|
462
|
-
In your pages (`AbstractPageComponent`), `form`
|
|
463
|
-
|
|
464
|
-
after the modifications, whoever calls the method (a listener, a callback, an `effect()`, ...):
|
|
512
|
+
In your pages (`AbstractPageComponent`), `form` and `reference` are signals too: write the form with `patchForm()`,
|
|
513
|
+
never in place, whoever calls the method (a listener, a callback, an `effect()`, ...). No `markForCheck()` is needed:
|
|
465
514
|
|
|
466
515
|
```ts
|
|
467
|
-
private readonly changeDetectorRef = inject(ChangeDetectorRef);
|
|
468
|
-
|
|
469
516
|
ngOnInit(): void {
|
|
470
517
|
super.ngOnInit();
|
|
471
518
|
this.sessionInfoWithApplicationService.prefillForm((info) => {
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
this.form.lastName = info?.lastName ?? null;
|
|
475
|
-
this.changeDetectorRef.markForCheck();
|
|
476
|
-
}
|
|
519
|
+
this.patchForm(['firstName'], info?.firstName ?? null);
|
|
520
|
+
this.patchForm(['lastName'], info?.lastName ?? null);
|
|
477
521
|
});
|
|
478
522
|
}
|
|
479
523
|
```
|
|
480
524
|
|
|
481
|
-
|
|
482
|
-
modifications of the method. After an `await`, or in another callback, call it again.
|
|
483
|
-
- A signal modified next to the form doesn't replace it: `set()` notifies Angular only when the value
|
|
484
|
-
changes (e.g. an amount recalculated identical), and only refreshes the views reading the signal.
|
|
485
|
-
|
|
486
|
-
If a service fills the form for the page, the page must still be notified: let the service return an
|
|
487
|
-
`Observable` (or take a callback), and call `markForCheck()` in the page.
|
|
525
|
+
See "Binding the fields of the form" above.
|
|
488
526
|
|
|
489
527
|
### Deriving a state from view queries
|
|
490
528
|
|
|
@@ -997,7 +1035,7 @@ Each `foehn-input-*` used in your view must:
|
|
|
997
1035
|
|
|
998
1036
|
> â ī¸ Don't forget to put a `track` with a unique identifier in the `@for` loop, otherwise the
|
|
999
1037
|
> validation won't be displayed. When a unique identifier such as `id` isn't possible, track
|
|
1000
|
-
> by
|
|
1038
|
+
> by `$index`: never by object a list of the form whose rows edit their item (see "Binding the fields of the form").
|
|
1001
1039
|
|
|
1002
1040
|
> âšī¸ In an Angular `@for` loop with a `FoehnInputComponent` component, if you validate your
|
|
1003
1041
|
> form, the errors returned are synchronized with the index of your components repeated in the
|
|
@@ -1024,7 +1062,7 @@ your `AbstractPageComponent`. This method will contain the following code:
|
|
|
1024
1062
|
* if an inventory item that was in error is removed, this prevents the error to be displayed
|
|
1025
1063
|
* to the next item that has taken it's index
|
|
1026
1064
|
*/
|
|
1027
|
-
this._gesdemService.validate(this.form).pipe(first()).subscribe();
|
|
1065
|
+
this._gesdemService.validate(this.form()).pipe(first()).subscribe();
|
|
1028
1066
|
```
|
|
1029
1067
|
|
|
1030
1068
|
Here is an example of a form page containing this method (1):
|
|
@@ -1064,7 +1102,7 @@ export class YourPageComponent
|
|
|
1064
1102
|
* if an inventory item that was in error is removed, this prevents the error to be displayed
|
|
1065
1103
|
* to the next item that has taken it's index
|
|
1066
1104
|
*/
|
|
1067
|
-
this._gesdemService.validate(this.form).pipe(first()).subscribe();
|
|
1105
|
+
this._gesdemService.validate(this.form()).pipe(first()).subscribe();
|
|
1068
1106
|
}
|
|
1069
1107
|
}
|
|
1070
1108
|
```
|
|
@@ -1273,13 +1311,16 @@ the removal event (2).
|
|
|
1273
1311
|
<!-- ... -->
|
|
1274
1312
|
<h2>{{ 'demande-page.vehicules' | fromDictionary }}</h2>
|
|
1275
1313
|
|
|
1314
|
+
@if (form(); as form) {
|
|
1276
1315
|
<app-vehicules-list
|
|
1277
|
-
[
|
|
1316
|
+
[model]="form.vehicules"
|
|
1317
|
+
(modelChange)="patchForm(['vehicules'], $event)"
|
|
1278
1318
|
name="vehicules"
|
|
1279
1319
|
[label]="'demande-page.vehicules-list' | fromDictionary"
|
|
1280
1320
|
[required]="true"
|
|
1281
1321
|
(removedVehicule)="handleRemovedVehicule()"
|
|
1282
1322
|
/>
|
|
1323
|
+
}
|
|
1283
1324
|
<!-- (1) Use of your list - (2) Call of the method saving the data in GESDEM to refresh the errors -->
|
|
1284
1325
|
|
|
1285
1326
|
<foehn-navigation
|
|
@@ -1308,7 +1349,7 @@ export class DemandePageComponent
|
|
|
1308
1349
|
* if an inventory item that was in error is removed, this prevents the error to be displayed
|
|
1309
1350
|
* to the next item that has taken it's index
|
|
1310
1351
|
*/
|
|
1311
|
-
this._gesdemService.save(this.form).pipe(first()).subscribe();
|
|
1352
|
+
this._gesdemService.save(this.form()).pipe(first()).subscribe();
|
|
1312
1353
|
}
|
|
1313
1354
|
}
|
|
1314
1355
|
```
|
|
@@ -1343,7 +1384,7 @@ What **not** to do:
|
|
|
1343
1384
|
```ts
|
|
1344
1385
|
isAmountFilled(): boolean {
|
|
1345
1386
|
// true after the input of '0', false once the form is loaded (0)
|
|
1346
|
-
return !!this.form?.amount;
|
|
1387
|
+
return !!this.form()?.amount;
|
|
1347
1388
|
}
|
|
1348
1389
|
```
|
|
1349
1390
|
|
|
@@ -1351,13 +1392,13 @@ What **to** do:
|
|
|
1351
1392
|
|
|
1352
1393
|
```ts
|
|
1353
1394
|
isAmountFilled(): boolean {
|
|
1354
|
-
const amount = this.form?.amount;
|
|
1395
|
+
const amount = this.form()?.amount;
|
|
1355
1396
|
return amount !== null && amount !== undefined && amount !== '';
|
|
1356
1397
|
}
|
|
1357
1398
|
|
|
1358
1399
|
getTotal(): number {
|
|
1359
1400
|
// Number() converts '12.50' as well as 12.5
|
|
1360
|
-
return Number(this.form?.amount ?? 0) + Number(this.form?.fees ?? 0);
|
|
1401
|
+
return Number(this.form()?.amount ?? 0) + Number(this.form()?.fees ?? 0);
|
|
1361
1402
|
}
|
|
1362
1403
|
```
|
|
1363
1404
|
|
|
@@ -1405,19 +1446,27 @@ export class BusinessForm {
|
|
|
1405
1446
|
`page-1.html`
|
|
1406
1447
|
|
|
1407
1448
|
```html
|
|
1449
|
+
@if (form(); as form) {
|
|
1408
1450
|
<foehn-input-text
|
|
1409
|
-
[
|
|
1451
|
+
[model]="form.identification.firstName"
|
|
1452
|
+
(modelChange)="patchForm(['identification', 'firstName'], $event)"
|
|
1410
1453
|
name="identification.firstName"
|
|
1411
1454
|
/>
|
|
1412
1455
|
<!-- 2 levels of depth -->
|
|
1413
1456
|
|
|
1414
1457
|
<foehn-input-text
|
|
1415
|
-
[
|
|
1458
|
+
[model]="form.identification.lastName"
|
|
1459
|
+
(modelChange)="patchForm(['identification', 'lastName'], $event)"
|
|
1416
1460
|
name="identification.lastName"
|
|
1417
1461
|
/>
|
|
1418
1462
|
|
|
1419
|
-
<foehn-boolean-checkbox
|
|
1463
|
+
<foehn-boolean-checkbox
|
|
1464
|
+
[model]="form.acceptCookies"
|
|
1465
|
+
(modelChange)="patchForm(['acceptCookies'], $event)"
|
|
1466
|
+
name="acceptCookies"
|
|
1467
|
+
/>
|
|
1420
1468
|
<!-- 1 level of depth -->
|
|
1469
|
+
}
|
|
1421
1470
|
```
|
|
1422
1471
|
|
|
1423
1472
|
- On the back-end side, you can handle your errors with the annotations (`@NotEmpty`, `@NotNull`, ...),
|
|
@@ -1470,7 +1519,8 @@ HTML page and the names of your errors must match.
|
|
|
1470
1519
|
|
|
1471
1520
|
```html
|
|
1472
1521
|
<foehn-input-text
|
|
1473
|
-
[
|
|
1522
|
+
[model]="form.identification.lastName"
|
|
1523
|
+
(modelChange)="patchForm(['identification', 'lastName'], $event)"
|
|
1474
1524
|
name="identification.lastName"
|
|
1475
1525
|
/>
|
|
1476
1526
|
```
|