@dsivd/prestations-ng 19.0.7 → 19.0.8

package/INTRODUCTION_ANGULAR_SIGNALS.md

@@ -0,0 +1,503 @@
+# Introduction aux Signaux Angular
+
+**Objectif** : compréhension solide de `signal()`, `computed()`, `effect()`, `input()`/`model()` et `linkedSignal()`, ainsi que des réflexes pour éviter les pièges les plus fréquents (mutation vs réassignation, sur-tracking dans `effect()`).
+
+---
+
+## Plan de session
+
+| #   | Bloc                                                        |
+| --- | ----------------------------------------------------------- |
+| 1.  | Pourquoi les signaux ?                                      |
+| 2.  | Les 3 primitives : `signal()`, `computed()`, `effect()`     |
+| 3.  | `input()` et `model()` : le nouveau contrat des composants  |
+| 4.  | `linkedSignal()` : l'état local qui se resynchronise        |
+| 5.  | `untracked()` : maîtriser les dépendances d'un `effect()`   |
+| 6.  | RxJS interop : signaux **et** RxJS, pas l'un contre l'autre |
+| 7.  | Le piège n°1 : mutation vs réassignation                    |
+
+---
+
+## 1. Pourquoi les signaux ?
+
+**Avant** : Angular détecte les changements en réexécutant (potentiellement) **tout l'arbre de composants** à chaque événement asynchrone intercepté par **Zone.js** (clic, timer, XHR...). Efficace historiquement, mais coûteux et peu prévisible à grande échelle.
+
+**Avec les signaux** : chaque valeur réactive **déclare explicitement** qui en dépend. Angular ne recalcule/ré-affiche que ce qui a réellement changé. C'est un modèle **fine-grained** et **déclaratif**.
+
+> 🎤 on ne "déclenche" plus la détection de changement, on **décrit un flux de données**. Le framework se charge de propager.
+
+---
+
+## 2. Les 3 primitives de base
+
+### `signal()` — une valeur réactive modifiable
+
+```ts
+readonly count = signal(0);
+
+increment(): void {
+  this.count.update(v => v + 1);
+  // ou, pour remplacer complètement la valeur :
+  this.count.set(5);
+}
+```
+
+⚠️ **il n'y a pas de `.mutate()`**. C'était dans la proposition initiale, retiré avant la version stable. On ne modifie jamais la valeur en place — on refait toujours passer par `.set()` / `.update()` avec une nouvelle référence (on y revient en détail au bloc 6).
+
+### `computed()` — une valeur dérivée, en lecture seule
+
+```ts
+readonly fullName = computed(() => `${this.firstName()} ${this.lastName()}`);
+```
+
+- Pure et synchrone, jamais de `.set()` à l'intérieur
+- Paresseux et mémoïsé : ne se recalcule que si une dépendance change
+- Les dépendances sont détectées **automatiquement** — pas besoin de les déclarer
+
+### `effect()` — un effet de bord
+
+```ts
+effect(() => {
+    localStorage.setItem('theme', this.theme());
+});
+```
+
+- S'exécute au moins une fois à l'initialisation
+- Se nettoie automatiquement à la destruction du composant
+- **Tout signal lu de façon synchrone dans le corps devient une dépendance** — y compris ceux qu'on ne voulait pas "trigger" (on y revient au bloc 5)
+
+**Exemple concret — les trois primitives ensemble :**
+
+```ts
+@Component({
+    selector: 'app-counter',
+    template: `
+        <p>Count : {{ count() }} ({{ isEven() ? 'pair' : 'impair' }})</p>
+        <button (click)="increment()">+1</button>
+    `,
+})
+export class CounterComponent {
+    readonly count = signal(0);
+    readonly isEven = computed(() => this.count() % 2 === 0);
+
+    constructor() {
+        // se déclenche à l'init, puis à chaque changement de `count`
+        effect(() => console.log(`count = ${this.count()}`));
+    }
+
+    increment(): void {
+        this.count.update((v) => v + 1);
+    }
+}
+```
+
+Remarque : `isEven` ne se recalcule que quand `count` change (mémoïsation), et le template ne se ré-affiche que sur la portion concernée — pas de re-render de tout le composant.
+
+### Mental model à donner à l'équipe
+
+| Je veux...                                           | J'utilise... |
+| ---------------------------------------------------- | ------------ |
+| Transformer / dériver une donnée                     | `computed()` |
+| Synchroniser avec le DOM, un service externe, logger | `effect()`   |
+
+🚩 **Le red flag à apprendre à repérer** : un `effect()` qui fait `.set()` sur un autre signal est presque toujours un `computed()` déguisé.
+
+```ts
+// 🔴 À corriger dès que vu en review
+effect(() => {
+  this.minYear.set(this.minDate()?.[0] ?? dayjs().year() - 100);
+});
+
+// 🟢 Ce que c'est vraiment
+readonly minYear = computed(() => this.minDate()?.[0] ?? dayjs().year() - 100);
+```
+
+---
+
+## 3. `input()` et `model()` : le nouveau contrat des composants
+
+### `input()` remplace `@Input()` (binding parent → enfant, une direction)
+
+```ts
+// Avant
+@Input() closeable = true;
+
+// Après
+readonly closeable = input(true);
+```
+
+### `model()` remplace la paire `@Input()` + `@Output()` (binding bidirectionnel)
+
+```ts
+// Avant
+@Input() isVisible = false;
+@Output() isVisibleChange = new EventEmitter<boolean>();
+
+// Après
+readonly isVisible = model(false);
+```
+
+```html
+<!-- deux sens -->
+<my-component [(isVisible)]="open" />
+```
+
+| Scénario                                                | Outil            |
+| ------------------------------------------------------- | ---------------- |
+| Le parent écrit, l'enfant lit seulement                 | `input()`        |
+| Le parent écrit, l'enfant réécrit, le parent lit        | `model()`        |
+| Le parent écrit, l'enfant réécrit, le parent ne lit pas | `linkedSignal()` |
+| Dérivé d'autres inputs                                  | `computed()`     |
+
+**Exemple concret — avant/après sur un composant type modale :**
+
+```ts
+// 🔴 Avant : @Input()/@Output() + synchronisation manuelle
+@Input() isVisible = false;
+@Output() isVisibleChange = new EventEmitter<boolean>();
+
+close(): void {
+  this.isVisible = false;
+  this.isVisibleChange.emit(false);
+}
+```
+
+```ts
+// 🟢 Après : model()
+readonly isVisible = model(false);
+
+close(): void {
+  this.isVisible.set(false);
+}
+```
+
+```html
+<!-- Côté parent : aucun code de synchronisation à écrire -->
+<app-modal [(isVisible)]="showModal" />
+```
+
+---
+
+## 4. `linkedSignal()` : l'état local qui se resynchronise
+
+Le chaînon manquant entre `computed()` (lecture seule) et `signal()` (aucune synchro automatique) : une valeur **modifiable localement**, mais qui **se réinitialise** quand une source change.
+
+```ts
+readonly options = input<string[]>([]);
+readonly selectedOption = linkedSignal(() => this.options()[0]);
+
+// L'utilisateur peut toujours écrire dessus...
+this.selectedOption.set('other value');
+// ...jusqu'à ce que `options` change, auquel cas ça se réinitialise.
+```
+
+🚩 **Red flag à apprendre** : un `effect()` qui reset un `signal()` classique quand une autre valeur change est un `linkedSignal()` qui s'ignore.
+
+```ts
+// 🔴
+readonly selectedOption = signal('');
+effect(() => this.selectedOption.set(this.options()[0]));
+
+// 🟢
+readonly selectedOption = linkedSignal(() => this.options()[0]);
+```
+
+**Exemple concret — un `select` dont les options viennent du parent :**
+
+```ts
+@Component({
+    selector: 'app-branch-select',
+    template: `
+        <select
+            [ngModel]="selectedBranch()"
+            (ngModelChange)="selectedBranch.set($event)"
+        >
+            @for (branch of branches(); track branch) {
+                <option [value]="branch">{{ branch }}</option>
+            }
+        </select>
+    `,
+})
+export class BranchSelectComponent {
+    readonly branches = input<string[]>([]);
+
+    // se réinitialise sur le premier élément à chaque changement de `branches`,
+    // mais reste librement modifiable par l'utilisateur entre deux changements
+    readonly selectedBranch = linkedSignal(() => this.branches()[0]);
+}
+```
+
+Sans `linkedSignal()`, il faudrait un `effect()` qui fait `.set()` sur un `signal()` classique à chaque changement de `branches` — exactement le red flag vu plus haut.
+
+---
+
+## 5. `untracked()` : maîtriser les dépendances d'un `effect()`
+
+Un `effect()` s'abonne à **tout** signal lu de façon synchrone dans son corps — pas seulement à ceux qu'on avait en tête comme déclencheurs. `untracked()` permet de lire une valeur **sans** créer cette dépendance.
+
+```ts
+effect(() => {
+    const id = this.userId(); // tracké
+    const config = untracked(() => this.appConfig()); // lu, mais pas tracké
+    this.analytics.logUserView(id, config);
+});
+```
+
+Cas d'usage le plus fréquent dans nos composants : un `effect()` qui lit **et** réécrit potentiellement le même signal (ex. corriger un `model()` de texte selon un préfixe).
+
+⚠️ **Piège à ne pas commettre** : ici, il ne faut **pas** faire `untracked(() => this.value())` sur le signal principal qu'on veut corriger — si on l'untrack, l'effect ne sera plus jamais redéclenché quand `value` change ailleurs (ex. la frappe de l'utilisateur), donc plus aucune correction ne se produira après le premier passage. `untracked()` sert à exclure des **signaux secondaires** qui ne doivent pas déclencher l'effect (un flag de config par exemple) — pas le signal principal qu'on observe.
+
+La sécurité contre la boucle infinie ne vient pas d'`untracked()` dans ce cas, mais de la **convergence** : l'effet ne réécrit que si une condition change réellement, donc le second passage (déclenché par sa propre écriture) devient un no-op.
+
+```ts
+private previousPrefix = DEFAULT_PREFIX; // simple champ de classe, pas un signal : pas besoin de réactivité dessus
+
+effect(() => {
+  let valueCopy = this.value();      // tracké : l'effect DOIT réagir aux changements de value
+  const prefix = this.prefix();      // tracké : l'effect DOIT réagir aux changements de prefix
+
+  // signal secondaire, hors sujet pour le déclenchement de cet effect : untracked() légitime
+  if (untracked(() => this.trimOnBlur())) {
+    valueCopy = valueCopy?.trim() ?? null;
+  }
+
+  // Le prefix a changé : on corrige value et on notifie le parent
+  if (!valueCopy?.includes(prefix)) {
+    const withoutOldPrefix = valueCopy?.includes(this.previousPrefix)
+      ? valueCopy.slice(this.previousPrefix.length)
+      : valueCopy;
+
+    this.value.set(withoutOldPrefix); // re-déclenche cet effect (voulu, cf. commentaire ci-dessous)
+    this.onUserInput(withoutOldPrefix); // vrai effet de bord (ex: notifier le parent)
+  }
+
+  // ⚠️ Ce .set() ci-dessus re-déclenche cet effect une 2e fois (attendu) :
+  // au 2e passage, valueCopy.includes(prefix) devient vrai → plus d'écriture → convergence.
+  this.previousPrefix = prefix;
+});
+```
+
+Ce qui rend ce `.set()` sur `value` légitime malgré le red flag de la section 2 : l'effect fait aussi `onUserInput()`, un vrai effet de bord (notifier le parent) — ce n'est pas une dérivation pure, donc pas un `computed()` déguisé.
+
+⚠️ `untracked()` ne remplace pas une garde de convergence. Il contrôle **ce qui déclenche** l'effet (signaux secondaires à exclure), pas le fait qu'une écriture sur le signal principal doive être conditionnelle pour éviter une boucle infinie — ce sont deux problèmes différents, qui se combinent souvent dans le même effect comme ci-dessus.
+
+---
+
+## 6. RxJS interop : signaux **et** RxJS, pas l'un contre l'autre
+
+> 🎤 **on ne migre pas tout le RxJS existant vers des signaux**. Les deux modèles répondent à des besoins différents, et le mélanger au mauvais endroit est aussi un piège.
+
+|           | Signal                                              | Observable (RxJS)                                                                                                      |
+| --------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Modèle    | **État** — une valeur à un instant T                | **Flux** — une séquence de valeurs dans le temps                                                                       |
+| Mode      | Pull (on lit `signal()` quand on veut)              | Push (on s'abonne, on reçoit)                                                                                          |
+| Fort pour | État de composant, dérivations synchrones, template | Async (HTTP, WebSocket), opérateurs (`debounceTime`, `switchMap`, `retry`, `combineLatest`...), annulation de requêtes |
+
+**Règle simple à donner à l'équipe** : si la donnée représente "un état actuel", signal. Si elle représente "une séquence d'événements dans le temps" avec de la composition/annulation à gérer, RxJS reste le bon outil — un appel HTTP en est l'exemple typique.
+
+### `toSignal()` — exposer un Observable comme un Signal
+
+Le cas le plus courant : un service qui expose un appel HTTP en `Observable`, consommé comme un `Signal` côté composant pour éviter le `| async` dans le template.
+
+```ts
+import { toSignal } from '@angular/core/rxjs-interop';
+
+private readonly userService = inject(UserService);
+
+// userService.getUser() retourne un Observable<User> (appel HTTP RxJS, inchangé)
+readonly user = toSignal(this.userService.getUser(), { initialValue: null });
+```
+
+- Se comporte comme le `| async` du template, mais utilisable partout (pas seulement en template)
+- Si l'Observable complète, le signal garde la dernière valeur émise
+- Si l'Observable erreur, l'erreur est relancée à la lecture du signal
+
+### `toObservable()` — exposer un Signal comme un Observable
+
+Le sens inverse : utile quand on veut piper un signal (ex. une valeur de recherche tapée par l'utilisateur) dans des opérateurs RxJS avant de déclencher un appel HTTP.
+
+```ts
+import { toObservable, toSignal } from '@angular/core/rxjs-interop';
+import { debounceTime, distinctUntilChanged, switchMap } from 'rxjs';
+
+readonly query = signal('');
+
+// on garde RxJS pour ce que RxJS fait bien : debounce + annulation de requêtes en vol
+private readonly results$ = toObservable(this.query).pipe(
+  debounceTime(300),
+  distinctUntilChanged(),
+  switchMap(query => this.searchService.search(query)), // Observable<Result[]>
+);
+
+readonly results = toSignal(this.results$, { initialValue: [] });
+```
+
+C'est l'exemple le plus parlant à montrer à l'équipe : **le signal pilote l'input utilisateur, RxJS gère le debounce/switchMap/annulation, et on ressort un signal côté template.** Aucun des deux modèles n'est sacrifié.
+
+⚠️ `toObservable()` doit être déclaré comme **champ de classe** (et non appelé à l'intérieur d'une méthode) car il a besoin d'un contexte d'injection au moment de sa création.
+
+### `rxResource()` — appels asynchrones pilotés par un signal, avec état loading/error inclus
+
+Alternative à `toSignal()` quand on veut aussi le suivi d'état (chargement, erreur, rechargement) sans le coder à la main. `rxResource()` accepte un `Observable` comme source de données, et se redéclenche automatiquement quand les signaux dont dépend la `request` changent.
+
+```ts
+import { rxResource } from '@angular/core/rxjs-interop';
+
+readonly userId = input.required<string>();
+
+readonly userResource = rxResource({
+  request: () => this.userId(),
+  loader: ({ request: id }) => this.userService.getUser(id), // Observable<User>
+});
+
+// dans le template : userResource.value(), userResource.isLoading(), userResource.error()
+```
+
+**Exemple concret — avant/après sur un appel HTTP géré à la main :**
+
+```ts
+// 🔴 Avant : subscribe() manuel + variables loading/error gérées à la main
+readonly user = signal<User | null>(null);
+readonly loading = signal(false);
+readonly error = signal<unknown>(null);
+
+ngOnInit(): void {
+  this.loading.set(true);
+  this.userService.getUser(this.userId()).subscribe({
+    next: user => { this.user.set(user); this.loading.set(false); },
+    error: err => { this.error.set(err); this.loading.set(false); },
+  });
+}
+```
+
+```ts
+// 🟢 Après : rxResource(), loading/error inclus, re-fetch automatique si userId() change
+readonly userResource = rxResource({
+  request: () => this.userId(),
+  loader: ({ request: id }) => this.userService.getUser(id),
+});
+// userResource.value(), userResource.isLoading(), userResource.error()
+```
+
+### Doit-on abandonner le pipe `async` ?
+
+Non, il n'est pas déprécié. Mais la tendance recommandée pour du code neuf est de préférer `toSignal()` dans la plupart des cas :
+
+- `toSignal()` se comporte comme le pipe `async`, mais la valeur obtenue est utilisable **partout** — pas seulement dans le template (dans un `computed()`, un `effect()`, en `input` d'un enfant...)
+- Une **seule souscription** même si la valeur est lue plusieurs fois dans le template (le pipe `async` utilisé deux fois sur le même flux crée deux souscriptions distinctes, sauf `shareReplay`)
+- Lectures cohérentes avec le reste du graphe de signaux (important avec `OnPush`/zoneless)
+
+Le pipe `async` garde toute sa légitimité quand l'`Observable` n'est consommé **que dans le template**, à un seul endroit, sans que la valeur ait besoin de sortir vers le reste de la classe — convertir en signal dans ce cas n'apporte rien.
+
+> 🎤 si la valeur ne sert qu'à l'affichage à un endroit précis, `| async` reste légitime. Si elle sert ailleurs dans le composant (calcul dérivé, passage à un enfant, logique dans un effet), `toSignal()`.
+
+### Ce qu'on ne migre **pas**
+
+> 🎤 afin d'éviter la sur-correction après cette session :
+
+- Les appels HTTP restent des `Observable` au niveau service (`HttpClient` retourne du RxJS, on ne change rien ici)
+- Les flux avec opérateurs de composition/temporisation (`debounceTime`, `combineLatest`, `retry`, `race`...) restent en RxJS
+- On ne convertit un `Observable` en `Signal` (via `toSignal()`) **qu'au bord** — c'est-à-dire au tout dernier moment, là où la donnée quitte le monde RxJS pour devenir un état à afficher, jamais au milieu d'une chaîne d'opérateurs
+
+    ```ts
+    // 🔴 Conversion prématurée en plein milieu du pipeline : un Signal
+    // n'est pas "pipeable", il faut repasser par toObservable() pour
+    // continuer la composition — aller-retour inutile
+    private readonly debounced = toSignal(
+      toObservable(this.query).pipe(debounceTime(300)),
+    );
+    private readonly results$ = toObservable(this.debounced).pipe(
+      distinctUntilChanged(),
+      switchMap(query => this.searchService.search(query)),
+    );
+    readonly results = toSignal(this.results$, { initialValue: [] });
+
+    // 🟢 Un seul point de conversion, à la toute fin de la chaîne
+    private readonly results$ = toObservable(this.query).pipe(
+      debounceTime(300),
+      distinctUntilChanged(),
+      switchMap(query => this.searchService.search(query)),
+    );
+    readonly results = toSignal(this.results$, { initialValue: [] });
+    ```
+
+    Ça vaut aussi entre les couches : un service peut composer entièrement en RxJS (`debounceTime`, `retry`, `combineLatest`...) et rester testable indépendamment de tout composant — c'est le composant consommateur, "au bord", qui convertit en signal au moment de l'affichage.
+
+---
+
+## 7. Le piège n°1 : mutation vs réassignation
+
+C'est **le** réflexe à perdre lorsqu'on vient de l'ère Zone.js : avant, muter un tableau ou un objet imbriqué "finissait par marcher" parce que la détection de changement repassait régulièrement sur tout. **Avec les signaux, ce n'est plus vrai** : seul `.set()` / `.update()` notifie les abonnés. Une mutation en place est invisible pour le signal, le template, et tout `computed()`/`effect()` qui en dépend.
+
+```ts
+// 🔴 No-op silencieux du point de vue du signal
+this.address().locality.name = 'newName';
+
+// 🟢 Nouvelle référence de premier niveau
+this.address.update((current) => ({
+    ...current,
+    locality: { ...current.locality, name: 'newName' },
+}));
+```
+
+Même logique pour les méthodes mutantes des tableaux :
+
+```ts
+// 🔴 push/splice/pop/shift/unshift/sort/reverse mutent en place
+this.model().push({ name: null, address: null });
+
+// 🟢 Toujours une nouvelle référence
+this.model.update((current) => [...current, { name: null, address: null }]);
+```
+
+...et pour `Map` / `Set` (piège sournois : `Map.prototype.set` porte le même nom que le `.set()` du signal) :
+
+```ts
+// 🔴 Ceci est Map.prototype.set, pas celui du signal — mute la même instance
+this.cache().set(key, value);
+
+// 🟢
+this.cache.update((current) => new Map(current).set(key, value));
+```
+
+> 💡 si une méthode modifie "en place" et ne renvoie pas un objet/tableau/Map/Set flambant neuf, elle mute — on la wrap dans une copie. `map`, `filter`, `slice`, `concat`, le spread : toujours sûrs.
+
+**Exemple concret — le plus percutant à montrer à l'équipe :**
+
+```ts
+@Component({
+    selector: 'app-contact-list',
+    template: `
+        @for (contact of contacts(); track contact.id) {
+            <p>{{ contact.name }}</p>
+        }
+        <button (click)="addBroken()">Ajouter (cassé)</button>
+        <button (click)="addFixed()">Ajouter (correct)</button>
+    `,
+})
+export class ContactListComponent {
+    readonly contacts = signal<Contact[]>([{ id: 1, name: 'Alice' }]);
+
+    addBroken(): void {
+        // 🔴 push() mute le tableau en place : le signal ne détecte rien,
+        // RIEN ne s'affiche à l'écran malgré la donnée bien présente en mémoire
+        this.contacts().push({ id: 2, name: 'Bob' });
+    }
+
+    addFixed(): void {
+        // 🟢 nouvelle référence : le @for se met à jour normalement
+        this.contacts.update((current) => [...current, { id: 2, name: 'Bob' }]);
+    }
+}
+```
+
+---
+
+## Checklist de fin de session
+
+- Je sais choisir entre `input()`, `model()`, `computed()`, `linkedSignal()` et `signal()`
+- Je sais repérer un `effect()` qui devrait être un `computed()`
+- Je sais repérer un `effect()` qui devrait être un `linkedSignal()`
+- Je ne mute plus jamais une valeur de signal en place — toujours `.set()`/`.update()` avec une nouvelle référence
+- Je sais quand utiliser `untracked()` dans un `effect()`
+- Je ne cherche pas à remplacer tout mon RxJS par des signaux — je garde RxJS pour l'async composé (HTTP, debounce, switchMap...) et je ne convertis en signal qu'au bord, avec `toSignal()`/`toObservable()`/`rxResource()`

package/eslint/component-path.mjs

@@ -0,0 +1,15 @@
+// Path of the component a linted template belongs to, `undefined` when the file is not a
+// template.
+//
+// An inline template is a virtual block whose path is derived from the `.ts`, and whose
+// name ends with `.html` too: `foo.component.ts/1_inline-template-….component.html`.
+// It has to be matched BEFORE the external template, otherwise it resolves to garbage.
+export function resolveComponentPath(filename) {
+  const inlineMatch = filename.match(/^(.*\.ts)(?:[/\\]|$)/);
+  if (inlineMatch) {
+    return inlineMatch[1];
+  }
+  return filename.endsWith(".html")
+    ? `${filename.slice(0, -".html".length)}.ts`
+    : undefined;
+}