@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.
Files changed (39) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +98 -3
  3. package/CONTRIBUTING.md +2 -2
  4. package/ESLINT_PLUGIN.md +103 -8
  5. package/GOOD_PRACTICES.md +79 -29
  6. package/UPGRADING_V19.md +187 -31
  7. package/eslint/configs/template-rules.mjs +5 -0
  8. package/eslint/configs/ts-recommended.mjs +4 -0
  9. package/eslint/form-reads.mjs +63 -0
  10. package/eslint/rules/index.mjs +4 -0
  11. package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  12. package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  13. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  14. package/eslint/rules/require-model-change.mjs +89 -0
  15. package/eslint/template-ast.mjs +12 -2
  16. package/fesm2022/dsivd-prestations-ng.mjs +907 -692
  17. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  18. package/package.json +1 -1
  19. package/schematics/migration-collection.json +5 -0
  20. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  21. package/schematics/utility/form-signal/class-migration.js +396 -0
  22. package/schematics/utility/form-signal/edits.js +34 -0
  23. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  24. package/schematics/utility/form-signal/page-classes.js +129 -0
  25. package/schematics/utility/form-signal/template-migration.js +666 -0
  26. package/src/eslint/configs/template-rules.mjs +5 -0
  27. package/src/eslint/configs/ts-recommended.mjs +4 -0
  28. package/src/eslint/form-reads.mjs +63 -0
  29. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  30. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -0
  31. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  32. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  33. package/src/eslint/rules/index.mjs +4 -0
  34. package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  35. package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  36. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  37. package/src/eslint/rules/require-model-change.mjs +89 -0
  38. package/src/eslint/template-ast.mjs +12 -2
  39. package/types/dsivd-prestations-ng.d.ts +234 -35
@@ -0,0 +1,99 @@
1
+ import { isComponentReceiver } from "../template-ast.mjs";
2
+ import { astOf, readsForm, resolveRoot } from "../form-reads.mjs";
3
+
4
+ /**
5
+ * ESLint rule: a `@for` over a list of the form of the page whose rows edit their
6
+ * item must not track the rows by the item itself (`track child`).
7
+ *
8
+ * The form is never modified in place: writing a field of an item (`patchForm()`,
9
+ * `patchItem()`) replaces the item with a copy. A row tracked by its item is then destroyed and
10
+ * created again at every input, and the field being edited loses the focus. Track the rows by
11
+ * `$index`, or by an identifier of the item (`track child.id`), which the copy keeps.
12
+ *
13
+ * A row edits its item when one of its elements has a `model` read from it
14
+ * (`[model]="child.firstName"`, `[(model)]="child"`). A list only displayed is left alone.
15
+ * `$any(child)` counts as `child`.
16
+ */
17
+
18
+ /**
19
+ * Whether the track expression of a `@for` is its item itself.
20
+ */
21
+ function tracksItemItself(forBlock) {
22
+ let track = astOf(forBlock.trackBy);
23
+ if (
24
+ track?.type === "Call" &&
25
+ track.receiver?.name === "$any" &&
26
+ track.args?.length === 1
27
+ ) {
28
+ track = track.args[0];
29
+ }
30
+ return (
31
+ track?.type === "PropertyRead" &&
32
+ isComponentReceiver(track.receiver) &&
33
+ track.name === forBlock.item?.name
34
+ );
35
+ }
36
+
37
+ export default {
38
+ meta: {
39
+ type: "problem",
40
+ docs: {
41
+ description:
42
+ "Disallow tracking by the item itself the rows of a @for editing a list of the form",
43
+ category: "Possible Errors",
44
+ recommended: true,
45
+ },
46
+ hasSuggestions: true,
47
+ schema: [],
48
+ messages: {
49
+ itemTrack:
50
+ "The rows of this list of the form are tracked by their item ('track {{item}}'): writing a field replaces the item, so its row is created again and the field being edited loses the focus. Track the rows by $index or by an identifier of the item.",
51
+ trackByIndex: "Track the rows by $index",
52
+ },
53
+ },
54
+
55
+ create(context) {
56
+ const candidates = [];
57
+ const editingBlocks = new Set();
58
+
59
+ return {
60
+ ForLoopBlock(node) {
61
+ if (
62
+ tracksItemItself(node) &&
63
+ readsForm(astOf(node.expression), node.parent)
64
+ ) {
65
+ candidates.push(node);
66
+ }
67
+ },
68
+ Element(node) {
69
+ const model = node.inputs?.find((input) => input.name === "model");
70
+ const root = model && resolveRoot(astOf(model.value), node);
71
+ if (root?.forBlock) {
72
+ editingBlocks.add(root.forBlock);
73
+ }
74
+ },
75
+ "Program:exit"() {
76
+ for (const forBlock of candidates) {
77
+ if (!editingBlocks.has(forBlock)) {
78
+ continue;
79
+ }
80
+ const { start, end } = astOf(forBlock.trackBy).sourceSpan;
81
+ context.report({
82
+ messageId: "itemTrack",
83
+ data: { item: forBlock.item.name },
84
+ loc: {
85
+ start: context.sourceCode.getLocFromIndex(start),
86
+ end: context.sourceCode.getLocFromIndex(end),
87
+ },
88
+ suggest: [
89
+ {
90
+ messageId: "trackByIndex",
91
+ fix: (fixer) => fixer.replaceTextRange([start, end], "$index"),
92
+ },
93
+ ],
94
+ });
95
+ }
96
+ },
97
+ };
98
+ },
99
+ };
@@ -1,6 +1,10 @@
1
1
  import { resolveComponentPath } from "../component-path.mjs";
2
2
  import { collectSignalNames } from "../signal-names.mjs";
3
- import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
3
+ import {
4
+ handlerExpressionOf,
5
+ isComponentReceiver,
6
+ isTwoWayBinding,
7
+ } from "../template-ast.mjs";
4
8
 
5
9
  /**
6
10
  * ESLint rule to detect signals referenced without being called in a template.
@@ -98,8 +102,9 @@ export default {
98
102
  BoundEvent(node) {
99
103
  // `[(x)]="expr"` generates a BoundEvent `xChange` whose handler IS the written
100
104
  // target. Its span is the one of the twin BoundAttribute expression: marking
101
- // the span neutralizes both copies at once.
102
- if (node.name?.endsWith("Change")) {
105
+ // the span neutralizes both copies at once. An explicit `(xChange)="…"` handler
106
+ // is a statement, checked as any other.
107
+ if (isTwoWayBinding(node)) {
103
108
  markHandled(handlerExpressionOf(node));
104
109
  }
105
110
  },
@@ -0,0 +1,89 @@
1
+ import { astOf, readsForm } from "../form-reads.mjs";
2
+
3
+ /**
4
+ * ESLint rule: a `foehn-*` component given a field of the form of the page with a
5
+ * one-way `[model]` must also listen to `(modelChange)`. Without it, what the user enters never
6
+ * reaches the form: the component changes its own model only. With the form held by a signal,
7
+ * bind `[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`.
8
+ *
9
+ * Only the models read from the form are checked (`form()`, `form.x`, and the names bound to
10
+ * it by `@if (form(); as form)`, `@let form = this.form()` or `@for (child of form.children)`):
11
+ * a one-way `[model]` is legitimate elsewhere (a table displaying a list, a menu...).
12
+ * `[(model)]` declares both bindings and is never reported.
13
+ *
14
+ * Not reported either, as the input of the user can't be lost: a component always disabled
15
+ * (`disabled="true"`, `[disabled]="true"`), the components which never write their model, and a
16
+ * component listening to `(userInput)`, whose handler writes the form.
17
+ */
18
+
19
+ /** Components which never write their model: they only display it. */
20
+ const READ_ONLY_COMPONENTS = new Set(["foehn-input-hidden", "foehn-table"]);
21
+
22
+ /**
23
+ * Whether the component is always disabled: a disabled component doesn't write its model, unless
24
+ * it is given `updateModelWhenDisabled`. A bare `disabled` gives `''`, which doesn't disable it.
25
+ */
26
+ function isAlwaysDisabled(node) {
27
+ const named = (name) => (binding) => binding.name === name;
28
+ const bindings = [...(node.attributes ?? []), ...(node.inputs ?? [])];
29
+ if (bindings.some(named("updateModelWhenDisabled"))) {
30
+ return false;
31
+ }
32
+ const disabled = astOf(node.inputs?.find(named("disabled"))?.value);
33
+ return (
34
+ node.attributes?.find(named("disabled"))?.value === "true" ||
35
+ (disabled?.type === "LiteralPrimitive" && disabled.value === true)
36
+ );
37
+ }
38
+
39
+ export default {
40
+ meta: {
41
+ type: "problem",
42
+ docs: {
43
+ description:
44
+ "Require (modelChange) next to a one-way [model] reading the form of the page",
45
+ category: "Possible Errors",
46
+ recommended: true,
47
+ },
48
+ schema: [],
49
+ messages: {
50
+ missing:
51
+ "'{{element}}' gets a field of the form with a one-way [model] without (modelChange): what the user enters never reaches the form. Add (modelChange), e.g. (modelChange)=\"patchForm([...], $event)\".",
52
+ },
53
+ },
54
+
55
+ create(context) {
56
+ const offset = (location) =>
57
+ typeof location === "number" ? location : location.offset;
58
+
59
+ return {
60
+ Element(node) {
61
+ if (!node.name?.startsWith("foehn-")) {
62
+ return;
63
+ }
64
+ const model = node.inputs?.find((input) => input.name === "model");
65
+ if (
66
+ !model ||
67
+ READ_ONLY_COMPONENTS.has(node.name) ||
68
+ node.outputs?.some(
69
+ (output) =>
70
+ output.name === "modelChange" || output.name === "userInput",
71
+ ) ||
72
+ isAlwaysDisabled(node) ||
73
+ !readsForm(astOf(model.value), node)
74
+ ) {
75
+ return;
76
+ }
77
+ const span = model.sourceSpan;
78
+ context.report({
79
+ messageId: "missing",
80
+ data: { element: node.name },
81
+ loc: {
82
+ start: context.sourceCode.getLocFromIndex(offset(span.start)),
83
+ end: context.sourceCode.getLocFromIndex(offset(span.end)),
84
+ },
85
+ });
86
+ },
87
+ };
88
+ },
89
+ };
@@ -1,8 +1,18 @@
1
1
  /**
2
- * Two subtleties of the Angular template AST that every template rule runs into.
3
- * Both are easy to get wrong, hence the shared names.
2
+ * Three subtleties of the Angular template AST that every template rule runs into.
3
+ * All are easy to get wrong, hence the shared names.
4
4
  */
5
5
 
6
+ /**
7
+ * Whether a `BoundEvent` is the one generated by a two-way binding `[(x)]="expr"`, whose
8
+ * handler is the target Angular writes into, not a statement.
9
+ *
10
+ * Its name alone can't tell: an explicit `(xChange)="refresh()"` has the same name. The
11
+ * key can: `x` for the two-way binding, `xChange` for the explicit handler.
12
+ */
13
+ export const isTwoWayBinding = (boundEvent) =>
14
+ boundEvent.name === `${boundEvent.keySpan?.details}Change`;
15
+
6
16
  /**
7
17
  * The expression carried by a `BoundEvent` handler.
8
18
  *