@dsivd/prestations-ng 19.2.0-beta.21 → 19.2.0-beta.23

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.
@@ -1,20 +1,29 @@
1
1
  import { isComponentReceiver } from "../template-ast.mjs";
2
- import { astOf, readsForm, resolveRoot } from "../form-reads.mjs";
2
+ import { astOf, resolveRoot } from "../form-reads.mjs";
3
3
 
4
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`).
5
+ * ESLint rule: a `@for` over a list of the form of the page, or over the list held by the
6
+ * `model` of the component, whose rows edit their item must not track the rows by the item
7
+ * itself (`track child`).
7
8
  *
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.
9
+ * These lists are never modified in place: writing a field of an item of the form
10
+ * (`patchForm()`, `patchItem()`) replaces the item with a copy, and a component extending
11
+ * `FoehnInputComponent` writes a new list in its model, its items replaced (`updateNgModel()`).
12
+ * A row tracked by its item is then destroyed and created again at every input, and the field
13
+ * being edited loses the focus; two items equal by value (e.g. two empty strings) even collide.
14
+ * Track the rows by `$index`, or by an identifier of the item (`track child.id`), which the copy
15
+ * keeps.
12
16
  *
13
17
  * 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.
18
+ * (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
19
+ * the row (`[model]="model()[i]"`, `let i = $index`). A list only displayed is left alone.
15
20
  * `$any(child)` counts as `child`.
16
21
  */
17
22
 
23
+ // The members holding a list whose items are replaced by a write: the form of the page, and
24
+ // the model of the component
25
+ const REPLACED_LISTS = new Set(["form", "model"]);
26
+
18
27
  /**
19
28
  * Whether the track expression of a `@for` is its item itself.
20
29
  */
@@ -34,12 +43,64 @@ function tracksItemItself(forBlock) {
34
43
  );
35
44
  }
36
45
 
46
+ /**
47
+ * Whether an expression reads a list whose items are replaced by a write: the form, or the
48
+ * model, directly or through a template name.
49
+ */
50
+ function readsReplacedList(expression, node) {
51
+ const root = resolveRoot(expression, node);
52
+ if (root?.forBlock) {
53
+ return readsReplacedList(
54
+ astOf(root.forBlock.expression),
55
+ root.forBlock.parent,
56
+ );
57
+ }
58
+ return REPLACED_LISTS.has(root?.member);
59
+ }
60
+
61
+ /**
62
+ * The `@for` whose list an expression reads at the index of the row (`model()[i]`,
63
+ * `form.children[$index].firstName`): an enclosing `@for` declaring the key as its `$index`
64
+ * (or an alias of it), over the same list, compared by its source.
65
+ */
66
+ function forBlockReadAtIndex(expression, node, textOf) {
67
+ for (let read = expression; read; read = read.receiver) {
68
+ if (read.type !== "KeyedRead" && read.type !== "SafeKeyedRead") {
69
+ continue;
70
+ }
71
+ const key = read.key;
72
+ if (key?.type !== "PropertyRead" || !isComponentReceiver(key.receiver)) {
73
+ continue;
74
+ }
75
+ for (let current = node; current; current = current.parent) {
76
+ if (current.type !== "ForLoopBlock") {
77
+ continue;
78
+ }
79
+ const variable = current.contextVariables?.find(
80
+ (contextVariable) => contextVariable.name === key.name,
81
+ );
82
+ if (!variable) {
83
+ continue;
84
+ }
85
+ // The innermost @for declaring the name binds it
86
+ if (
87
+ variable.value === "$index" &&
88
+ textOf(read.receiver) === textOf(astOf(current.expression))
89
+ ) {
90
+ return current;
91
+ }
92
+ break;
93
+ }
94
+ }
95
+ return undefined;
96
+ }
97
+
37
98
  export default {
38
99
  meta: {
39
100
  type: "problem",
40
101
  docs: {
41
102
  description:
42
- "Disallow tracking by the item itself the rows of a @for editing a list of the form",
103
+ "Disallow tracking by the item itself the rows of a @for editing a list of the form, or of the model of the component",
43
104
  category: "Possible Errors",
44
105
  recommended: true,
45
106
  },
@@ -47,7 +108,7 @@ export default {
47
108
  schema: [],
48
109
  messages: {
49
110
  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.",
111
+ "The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, 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
112
  trackByIndex: "Track the rows by $index",
52
113
  },
53
114
  },
@@ -55,22 +116,34 @@ export default {
55
116
  create(context) {
56
117
  const candidates = [];
57
118
  const editingBlocks = new Set();
119
+ const textOf = (expression) =>
120
+ context.sourceCode.text
121
+ .slice(expression.sourceSpan.start, expression.sourceSpan.end)
122
+ .replace(/\s+/g, "");
58
123
 
59
124
  return {
60
125
  ForLoopBlock(node) {
61
126
  if (
62
127
  tracksItemItself(node) &&
63
- readsForm(astOf(node.expression), node.parent)
128
+ readsReplacedList(astOf(node.expression), node.parent)
64
129
  ) {
65
130
  candidates.push(node);
66
131
  }
67
132
  },
68
133
  Element(node) {
69
134
  const model = node.inputs?.find((input) => input.name === "model");
70
- const root = model && resolveRoot(astOf(model.value), node);
135
+ if (!model) {
136
+ return;
137
+ }
138
+ const expression = astOf(model.value);
139
+ const root = resolveRoot(expression, node);
71
140
  if (root?.forBlock) {
72
141
  editingBlocks.add(root.forBlock);
73
142
  }
143
+ const readAtIndex = forBlockReadAtIndex(expression, node, textOf);
144
+ if (readAtIndex) {
145
+ editingBlocks.add(readAtIndex);
146
+ }
74
147
  },
75
148
  "Program:exit"() {
76
149
  for (const forBlock of candidates) {
@@ -953,12 +953,39 @@ class FoehnInputComponent {
953
953
  handleChange(value) {
954
954
  this.triggerUserInput(value);
955
955
  }
956
+ /**
957
+ * Writes the model, which the page gets through `modelChange`: always a new object or array, never the model
958
+ * modified in place. The model is a signal, which ignores the value it already holds: no `modelChange` would be
959
+ * emitted, and the page would never get the change. Also makes the model known (`model_`), and leaves the model
960
+ * of a disabled component alone, unless `updateModelWhenDisabled`.
961
+ *
962
+ * @param value the new model
963
+ */
956
964
  updateNgModel(value) {
957
965
  this.model_ = value;
958
966
  if (!this.disabled() || this.updateModelWhenDisabled()) {
959
967
  this.model.set(value);
960
968
  }
961
969
  }
970
+ /**
971
+ * Writes a value at a path of the model, in a new model: the objects and arrays along the path are copied, the
972
+ * others are kept as they are (`ObjectPathHelper`), and the result goes through `updateNgModel()`. Bind a field of
973
+ * an object edited as is with `[model]="model()?.firstName" (modelChange)="patchNgModel(['firstName'], $event)"`,
974
+ * or replace an item of a list with `patchNgModel([index], item)`. The same value changes nothing.
975
+ *
976
+ * @param path the keys and indexes leading to the value, e.g. `['address', 'street']` or `[index]`
977
+ * @param value the new value (`null` and `undefined` included: the model of the `foehn-*` components can be)
978
+ * @throws Error when the page gives no model and `emptyModel()` neither, or when an object of the path is `null`
979
+ * or `undefined`
980
+ */
981
+ patchNgModel(path, value) {
982
+ const current = this.model() ?? this.emptyModel();
983
+ if (current === null || current === undefined) {
984
+ throw new Error(`patchNgModel() of '${this.name()}': the page gives no model, override emptyModel() to give one`);
985
+ }
986
+ // patchByKeys(): TypeScript can't resolve the typed path for the generic T of this class
987
+ this.updateNgModel(ObjectPathHelper.patchByKeys(current, path, value));
988
+ }
962
989
  hasErrorsToDisplay() {
963
990
  return (this.hasErrors() &&
964
991
  (!this.disabled() || this.showErrorWhenDisabled()));
@@ -1167,6 +1194,16 @@ class FoehnInputComponent {
1167
1194
  hasValueToDisplay(value) {
1168
1195
  return ObjectHelper.hasAnyValue(value);
1169
1196
  }
1197
+ /**
1198
+ * The model `patchNgModel()` starts from when the page gives none (`null` or `undefined`): none by default. To
1199
+ * override in a component whose model can be missing, e.g. `return new Owner();`, the objects of its paths
1200
+ * included.
1201
+ *
1202
+ * @returns a new empty model, or `null`
1203
+ */
1204
+ emptyModel() {
1205
+ return null;
1206
+ }
1170
1207
  isEmpty(data) {
1171
1208
  return data === null || data === undefined || data === '';
1172
1209
  }
@@ -3342,8 +3379,12 @@ class AbstractPageComponent {
3342
3379
  */
3343
3380
  form = signal(null, ...(ngDevMode ? [{ debugName: "form" }] : /* istanbul ignore next */ []));
3344
3381
  /**
3345
- * The reference of the demand, set when the form is loaded. A template, a `computed()` or an `effect()` reading it
3346
- * follows it, also when the page sets it: read it with `untracked()` in an `effect()` which must not follow it.
3382
+ * The reference of the demand, set when the form is loaded: `undefined` as long as no form was loaded from the
3383
+ * backend, then its reference, or `null` when it has none (a demand not created yet). A page which doesn't set it
3384
+ * itself can so derive "the form is loaded" from it: `computed(() => this.reference() !== undefined)`.
3385
+ *
3386
+ * A template, a `computed()` or an `effect()` reading it follows it, also when the page sets it: read it with
3387
+ * `untracked()` in an `effect()` which must not follow it.
3347
3388
  */
3348
3389
  reference = signal(undefined, ...(ngDevMode ? [{ debugName: "reference" }] : /* istanbul ignore next */ []));
3349
3390
  _destroyRef = inject(DestroyRef);