@dsivd/prestations-ng 19.2.0-beta.2 → 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.
Files changed (55) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +396 -0
  3. package/CONTRIBUTING.md +74 -4
  4. package/ESLINT_PLUGIN.md +103 -8
  5. package/GOOD_PRACTICES.md +731 -380
  6. package/INTRODUCTION_ANGULAR_SIGNALS.md +199 -154
  7. package/UPGRADING_V18.md +5 -5
  8. package/UPGRADING_V19.md +439 -18
  9. package/eslint/configs/spec-ts-recommended.mjs +34 -0
  10. package/eslint/configs/template-recommended.mjs +2 -0
  11. package/eslint/configs/template-rules.mjs +11 -2
  12. package/eslint/configs/ts-recommended.mjs +6 -0
  13. package/eslint/configs/ts-rules.mjs +6 -2
  14. package/eslint/form-reads.mjs +63 -0
  15. package/eslint/index.mjs +17 -0
  16. package/eslint/rules/index.mjs +4 -0
  17. package/eslint/rules/no-direct-signal-mutation.mjs +58 -20
  18. package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  19. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  20. package/eslint/rules/require-model-change.mjs +89 -0
  21. package/eslint/template-ast.mjs +12 -2
  22. package/fesm2022/dsivd-prestations-ng.mjs +2766 -2073
  23. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  24. package/package.json +1 -2
  25. package/schematics/migration-collection.json +5 -0
  26. package/schematics/ng-add/index.js +2 -4
  27. package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
  28. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  29. package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
  30. package/schematics/utility/form-signal/class-migration.js +396 -0
  31. package/schematics/utility/form-signal/edits.js +34 -0
  32. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  33. package/schematics/utility/form-signal/page-classes.js +129 -0
  34. package/schematics/utility/form-signal/template-migration.js +666 -0
  35. package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
  36. package/src/eslint/configs/__tests__/configs.test.mjs +46 -2
  37. package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
  38. package/src/eslint/configs/template-recommended.mjs +2 -0
  39. package/src/eslint/configs/template-rules.mjs +11 -2
  40. package/src/eslint/configs/ts-recommended.mjs +6 -0
  41. package/src/eslint/configs/ts-rules.mjs +6 -2
  42. package/src/eslint/form-reads.mjs +63 -0
  43. package/src/eslint/index.mjs +17 -0
  44. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  45. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -0
  46. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  47. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  48. package/src/eslint/rules/index.mjs +4 -0
  49. package/src/eslint/rules/no-direct-signal-mutation.mjs +58 -20
  50. package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  51. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  52. package/src/eslint/rules/require-model-change.mjs +89 -0
  53. package/src/eslint/template-ast.mjs +12 -2
  54. package/types/dsivd-prestations-ng.d.ts +652 -240
  55. package/dsivd-prestations-ng-19.2.0-beta.2.tgz +0 -0
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, and the signal rules of
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
+ ```