@dsivd/prestations-ng 19.0.8 → 19.1.0

package/GOOD_PRACTICES.md

@@ -0,0 +1,1223 @@
+# Utilisation technique (DEV)
+
+> Ce guide décrit les bonnes pratiques pour développer une prestation avec `prestations-ng`.
+> Il a été mis à jour pour la version **v19+** : composants **standalone**, **signals** et
+> fonction **`inject`** (plus de modules, plus d'injection par constructeur).
+>
+> 📚 Pour aller plus loin :
+> [ANGULAR_SIGNALS.md](ANGULAR_SIGNALS.md) · [COMPONENTS.md](COMPONENTS.md) · [UPGRADING_V19.md](UPGRADING_V19.md)
+
+## Sommaire
+
+- [Documentation](good-practices#documentation)
+- [Mise à jour de la librairie](good-practices#mise___jour_de_la_librairie)
+- [Accessibilité](good-practices#accessibilit_)
+    - [Structure HTML](good-practices#structure_html)
+    - [Le focus](good-practices#le_focus)
+    - [La balise `<label>`](good-practices#la_balise__code__lt_label_gt___code_)
+    - [La balise `<ul>` ou `<ol>`](good-practices#la_balise__code__lt_ul_gt___code__ou__code__lt_ol_gt___code_)
+    - [La balise `<fieldset>` et `<legend>`](good-practices#la_balise__code__lt_fieldset_gt___code__et__code__lt_legend_gt___code_)
+    - [Liseuse d'écran (afficher / masquer)](good-practices#liseuse_d__cran__afficher___masquer_)
+    - [Une page prestations-ng](good-practices#une_page_prestations-ng)
+- [Le routage de vos pages](good-practices#le_routage_de_vos_pages)
+    - [Formulaire simple](good-practices#formulaire_simple)
+    - [Formulaire complexe (sous-routes)](good-practices#formulaire_complexe__sous-routes_)
+- [Création d'un composant réutilisable](good-practices#cr_ation_d_un_composant_r_utilisable)
+    - [Exemple avec foehn-input-date de prestations-ng](good-practices#exemple_avec_foehn-input-date_de_prestations-ng)
+    - [Afficher la validation globale du composant](good-practices#afficher_la_validation_globale_du_composant)
+    - [Éviter des problèmes d'affichage d'erreurs dans une boucle `@for`](good-practices#_viter_des_probl_mes_d_affichage_d_erreurs_dans_une_boucle__code__for__code_)
+- [Validation du formulaire](good-practices#validation_du_formulaire)
+    - [Gestion standard](good-practices#gestion_standard)
+    - [Gestion manuelle](good-practices#gestion_manuelle)
+        - [Back-end](good-practices#back-end)
+        - [Front-end](good-practices#front-end)
+- [Validation manuelle d'un composant](good-practices#validation_manuelle_d_un_composant)
+    - [Cacher une erreur](good-practices#cacher_une_erreur)
+    - [Afficher une erreur](good-practices#afficher_une_erreur)
+
+> ⚠️ Dans toutes vos pages HTML vous devez avoir un `<foehn-form>` et celui-ci **ne peut pas être
+> conditionnel** (pas de `@if` autour de `<foehn-form>`).
+
+## Documentation
+
+- [PrestaKit](https://www.vd.ch/toutes-les-autorites/departements/departement-des-infrastructures-et-des-ressources-humaines-dirh/direction-generale-du-numerique-et-des-systemes-dinformation-dgnsi/prestakit-sdk-pour-le-developpement-des-prestations-en-ligne/)
+- [prestations-ng](https://dsi-vd.github.io/prestations-ng/)
+- [prestations-ng (doc autogénérée)](https://dsi-vd.github.io/prestations-ng/generateddoc/)
+- [foehn](https://dsi-vd.github.io/foehn-design-system/components/detail/formulaire-prestation--default.html) (Charte graphique)
+- [CSS](https://www.w3schools.com/css/default.asp)
+    - [Bootstrap](https://getbootstrap.com/docs/5.3/layout/grid/)
+    - [Flex - Bootstrap](https://getbootstrap.com/docs/5.3/utilities/flex/)
+    - [Flex](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)
+- [HTML](https://www.w3schools.com/html/default.asp)
+    - [Éléments de section](https://www.alsacreations.com/article/lire/1376-html5-section-article-nav-header-footer-aside.html)
+    - [Description list](https://www.w3schools.com/tags/tag_dl.asp)
+- [RXJS](https://rxjs-dev.firebaseapp.com/)
+
+## Mise à jour de la librairie
+
+> ℹ️ Maintenez à jour vos librairies en vous inscrivant sur la page [PrestaKit](https://www.vd.ch/toutes-les-autorites/departements/departement-des-infrastructures-et-des-ressources-humaines-dirh/direction-generale-du-numerique-et-des-systemes-dinformation-dgnsi/prestakit-sdk-pour-le-developpement-des-prestations-en-ligne/)
+> et vous serez ainsi notifié des nouvelles releases. Cela vous permettra de profiter des corrections
+> de bug, améliorations et nouvelles fonctionnalités.
+>
+> Prenez le temps de lire le [changelog](CHANGELOG.md) de **prestations-ng** à chaque nouvelle release.
+>
+> N'hésitez pas à ouvrir des tickets JIRA (PRESTAKIT-xxx) dans [PrestaKit (anc SDK Cyber)](https://issuetracker.etat-de-vaud.ch/outils/issuetracker/browse/PRESTAKIT)
+> pour signaler des bugs ou même à faire des propositions d'améliorations afin de
+> [contribuer](CONTRIBUTING.md) au développement de prestations-ng.
+
+Mettre à jour la librairie prestations-ng (npm) :
+
+```bash
+ng update @dsivd/prestations-ng
+```
+
+## Accessibilité
+
+> ℹ️ En développant des prestations pour l'État, nous devons faire tout notre possible pour rendre nos
+> pages web les plus accessibles possibles au grand public.
+>
+> Prestations-ng fait une bonne partie du boulot pour nous mais c'est au développeur de prendre le
+> soin de mettre les efforts qu'il faut pour que la prestation reste accessible.
+
+### Structure HTML
+
+> ⚠️ Nous recommandons :
+>
+> - une seule balise h1 (`<h1>`)
+> - respecter la hiérarchie h1, h2, h3..
+> - regrouper vos informations dans des sections (`<section>`) si vous avez plusieurs h2 (`<h2>`)
+> - utiliser la classe CSS `col-md-8` de Bootstrap pour définir la largeur de votre formulaire
+> - organisez votre texte avec des paragraphes (`<p>`)
+> - utiliser les balises `<dl>`, `<dt>` et `<dd>` pour afficher des clés / valeurs (voir [foehn-recap-section](https://dsi-vd.github.io/prestations-ng/recap))
+> - utiliser [foehn-abbr](https://dsi-vd.github.io/prestations-ng/misc) pour les abréviations tant que possible et sinon la balise abbr (`<abbr>`)
+
+Ce qu'il ne faut **pas** faire :
+
+```html
+<h1>...</h1>
+    <h3>...</h3>
+        <h2>...</h2>
+            <h6>...</h6>
+            ...
+        ...
+    ...
+```
+
+Ce qu'il **faut** faire :
+
+```html
+<h1>...</h1>
+    <section>
+        <h2>...</h2>
+            <h3>...</h3>
+                <h4>...</h4>
+                ...
+            ...
+    </section>
+        <h2>...</h2>
+        ...
+    <section>
+    ...
+```
+
+Quelques attributs HTML utiles :
+
+- Pour les images (`<img>`)
+    - `title="[texte explicite ici]"`
+    - `alt="[texte explicite ici]"`
+- Pour les liens (`<a>`)
+    - `title="[texte explicite ici]"`
+    - `target="_blank"`
+- [Rendre les balises accessibles](https://www.w3.org/TR/wai-aria-1.2/#intro_ria_accessibility)
+    - [`aria-*`](https://w3c.github.io/using-aria/#aria-states-and-properties-aria-attributes)
+    - [`role`](https://www.w3.org/WAI/PF/HTML/wiki/RoleAttribute)
+
+### Le focus
+
+> ⚠️ Il est important que le focus dans une page HTML soit maîtrisé. Si le focus est perdu, alors la
+> liseuse d'écran le sera aussi.
+>
+> Si, par exemple, on ouvre une modale en cliquant sur un bouton, alors à la fermeture de la modale,
+> le focus doit être remis sur le bouton déclencheur.
+
+Exemple :
+
+```html
+<button
+    type="button"
+    class="btn btn-secondary"
+    (click)="openModal()"
+    #modalTrigger
+>
+    <!-- on déclare le déclencheur de la modale -->
+    Open Modal
+</button>
+<foehn-modal
+    modalHeaderText="Modal dialog"
+    modalSize="modal-lg"
+    [isModalVisible]="isModalVisible"
+    (isModalVisibleChange)="updateVisibilityStatus($event)"
+    [modalTriggerHtmlElement]="modalTrigger"
+>
+    <!-- on utilise le déclencheur -->
+    <div>Here is the dialog</div>
+</foehn-modal>
+```
+
+### La balise `<label>`
+
+> ⚠️ Tous nos composants `foehn-input-*` disposent d'une balise label ([`<label>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/label))
+> qui décrit le champ de saisie. Il est important que celle-ci soit remplie avec un contenu explicite.
+>
+> Si pour une raison quelconque, le métier ne souhaite pas l'afficher, vous devez tout de même la
+> renseigner et ajouter un attribut `[isLabelSrOnly]="true"`. Le label ne sera pas affiché mais
+> uniquement lu par la liseuse d'écran.
+
+Exemple :
+
+```html
+<foehn-input-number
+    name="..."
+    [(model)]="..."
+    [label]="'Le texte que la liseuse va lire'"
+    [isLabelSrOnly]="true"
+    [required]="..."
+    [maxlength]="..."
+/>
+```
+
+> 💡 `label`, `isLabelSrOnly`, `required`, ... sont désormais des **input signals** côté composant.
+> Vous continuez à les alimenter depuis le template parent via un binding `[label]="..."`.
+> À l'intérieur du composant, vous les lisez en les invoquant : `label()`, `required()`, ...
+
+### La balise `<ul>` ou `<ol>`
+
+> ⚠️
+>
+> - L'élément [`<ul>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ul) doit être utilisé
+>   pour regrouper plusieurs éléments qui n'ont pas de relation d'ordre. Si on hésite entre
+>   [`<ol>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ol) et
+>   [`<ul>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ul), on se demandera si changer
+>   l'ordre des éléments de la liste a un impact : si le déplacement d'un élément change la
+>   signification, cela signifie que l'ordre est important et qu'il faudra utiliser
+>   [`<ol>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ol), sinon l'ordre n'importe pas
+>   et [`<ul>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ul) peut être utilisé.
+> - Si [`<ol>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ol) ou
+>   [`<ul>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ul) ne contient qu'un seul élément
+>   [`<li>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/li) (non dynamique), alors on se
+>   demandera si l'utilisation d'une liste est nécessaire et si un paragraphe
+>   ([`<p>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/p)) ne serait pas une meilleure
+>   option.
+> - Ne **JAMAIS** mettre une autre balise que [`<li>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/li)
+>   entre deux balises [`<ol>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ol) ou
+>   [`<ul>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/ul).
+
+Exemple :
+
+```html
+<ul>
+  <li>un artichaut</li>
+  <li>Les trucs pour le gâteau
+  <!-- On voit que </li> n'est pas là -->
+    <ul>
+      <li>trois œufs</li>
+      <li>La génoise
+      <!-- Là on ouvre une autre liste -->
+        <ul>
+          <li>100g de sucre</li>
+          <li>un œuf</li>
+          <li>150g de farine</li>
+        </ul>
+      </li> <!-- On ferme la liste la plus imbriquée -->
+      <li>200g de chocolat</li>
+    </ul>
+  <!-- On ferme la liste imbriquée avec </li> -->
+  </li>
+  <li>De l'essuie-tout</li>
+  <li>A faire dans l'ordre pour une belle vaisselle
+    <ol>
+      <li>Remplir le lave vaisselle</li>
+      <li>Mettre une pastille pour lave vaisselle</li>
+      <li>Fermer la porte du lave vaisselle</li>
+      <li>Lancer le lave vaisselle</li>
+    </ol>
+  </li>
+</ul>
+```
+
+### La balise `<fieldset>` et `<legend>`
+
+> ⚠️ L'élément HTML [`<fieldset>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/fieldset) est
+> utilisé afin de regrouper plusieurs contrôles interactifs ainsi que des étiquettes
+> ([`<label>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/label)) dans un formulaire HTML
+> et on doit lui associer une légende
+> ([`<legend>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/legend)) décrivant ce groupe.
+>
+> L'élément HTML [`<legend>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/legend) représente
+> une légende pour le contenu de son élément parent
+> [`<fieldset>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/fieldset). Il ne peut pas être
+> utilisé tout seul.
+
+Exemple :
+
+```html
+<form>
+  <fieldset>
+    <legend>Choose your favorite monster</legend>
+
+    <input type="radio" id="kraken" name="monster" value="K" />
+    <label for="kraken">Kraken</label><br />
+
+    <input type="radio" id="sasquatch" name="monster" value="S" />
+    <label for="sasquatch">Sasquatch</label><br />
+
+    <input type="radio" id="mothman" name="monster" value="M" />
+    <label for="mothman">Mothman</label>
+  </fieldset>
+</form>
+```
+
+### Liseuse d'écran (afficher / masquer)
+
+> ⚠️ Il est important de garder en tête qu'une liseuse d'écran va parcourir notre code HTML. De ce
+> fait, nous pouvons à tout moment décider de lui afficher explicitement du contenu à lire ou de lui
+> masquer du contenu pour ne pas surcharger l'information.
+
+- Afficher uniquement pour la liseuse : utiliser la classe CSS `sr-only`
+- Masquer du contenu à la liseuse : utiliser l'attribut `aria-hidden="true"`
+
+Exemple :
+
+```html
+<a href="https://www.vd.ch">
+    <span class="sr-only">
+        <!-- Afficher uniquement pour la liseuse d'écran -->
+        Retour à la page d'accueil
+    </span>
+    <img
+        aria-hidden="true"
+        class="img-fluid footer-logo"
+        src="[url_vers_mon_image]"
+        alt="Canton de Vaud"
+    />
+    <!-- Masquer uniquement pour la liseuse d'écran -->
+</a>
+```
+
+Le résultat de l'exemple ci-dessus sera un lien représenté par une image pour les voyants et un lien
+avec du texte pour les non-voyants.
+
+### Une page prestations-ng
+
+1. Étendre la classe abstraite `AbstractPageComponent` en spécifiant un modèle
+2. Ajouter un titre h1 en utilisant `setPageTitle`
+3. Implémenter la fonction `newForm`
+4. Ajouter le `<foehn-form>` dans la page (⚠️ **il ne doit pas être conditionnel**)
+5. La première balise d'en-tête de votre page doit être un h2 (`<h2>`)
+6. Ajouter `<foehn-navigation>`
+7. Si vous disposez de plusieurs pages, utiliser le composant `<foehn-page-counter>`
+
+`page-one.component.ts`
+
+```ts
+@Component({
+    templateUrl: './page-one.component.html',
+    imports: [
+        // chaque composant importe ce dont il a besoin dans son template
+        FoehnFormComponent,
+        FoehnNavigationComponent,
+        FoehnPageCounterComponent,
+        SdkDictionaryPipe,
+        // ... vos composants foehn-* utilisés dans le template
+    ],
+})
+export class PageOneComponent extends AbstractPageComponent<BusinessForm> implements OnInit {
+    ngOnInit(): void {
+        super.ngOnInit();
+        // point (2) : ajoutera le titre h1
+        this.setPageTitle(this._dictionaryService.getKeySync('page.one.title'));
+    }
+
+    // point (3)
+    newForm(): BusinessForm {
+        return new BusinessForm();
+    }
+}
+```
+
+> 💡 Plus de `constructor` : les dépendances de `AbstractPageComponent` (dont `_dictionaryService`)
+> sont injectées via `inject()` dans la classe abstraite. `activatedRoute` n'est donc plus un
+> paramètre de constructeur à passer.
+
+`page-one.component.html`
+
+```html
+<div class="container mt-5">
+    <foehn-page-counter />
+    <!-- point (7) : si besoin -->
+
+    <!-- point (4) : doit toujours être présent dans la page et pas conditionnel (pas de @if) -->
+    <foehn-form>
+        <div class="row">
+            <div class="col-md-8">
+                <!-- point (5) : toujours avoir un <h2> en premier dans votre page -->
+                <h2>{{ 'La_clé_du_dictionnaire_de_votre_titre_H2_ici' | fromDictionary }}</h2>
+
+                <!-- [VOS COMPOSANTS FOEHN ICI] -->
+
+                <foehn-navigation
+                    id="navigation"
+                    (onPrevious)="previous()"
+                    (onNext)="send()"
+                />
+                <!-- point (6) -->
+            </div>
+        </div>
+    </foehn-form>
+</div>
+```
+
+## Le routage de vos pages
+
+### Formulaire simple
+
+`app.routes.ts`
+
+```ts
+export const routes: Routes = [
+    {
+        path: '',
+        component: PageWrapperComponent,
+        data: { root: true },
+        children: [
+            { path: '', component: PageOneComponent, canActivate: [GesdemLoaderGuard] },
+            { path: '404', component: FoehnNotfoundComponent },
+            { path: 'erreur', component: GesdemErrorComponent },
+            {
+                path: ':reference',
+                children: [
+                    { path: 'page-1', component: PageOneComponent, data: { order: 1 } },
+                    // {...},
+                    // ...
+                    { path: 'erreur', component: GesdemErrorComponent },
+                    { path: '404', component: FoehnNotfoundComponent },
+                    { path: '', redirectTo: 'page-1', pathMatch: 'full' },
+                ],
+                canActivate: [GesdemLoaderGuard],
+            },
+            { path: '**', redirectTo: '/404', pathMatch: 'full' },
+        ],
+    },
+];
+```
+
+### Formulaire complexe (sous-routes)
+
+> ℹ️ Préférez l'utilisation de **sous-routes** (`*.routes.ts`) pour regrouper vos routes et ainsi
+> mieux structurer votre projet.
+>
+> Comme il n'y a plus de modules (composants **standalone**), on ne charge plus un `*.module.ts` mais
+> un fichier de routes qui exporte une constante `Routes`. Voir [UPGRADING_V19.md](UPGRADING_V19.md)
+> pour le détail de la migration.
+
+`app.routes.ts`
+
+```ts
+export const routes: Routes = [
+    {
+        path: '',
+        component: PageWrapperComponent,
+        children: [
+            {
+                path: 'welcome',
+                loadChildren: () =>
+                    import('./modules/welcome/welcome.routes').then((m) => m.welcome_routes),
+            },
+            {
+                path: 'inscription',
+                loadChildren: () =>
+                    import('./modules/inscription/inscription.routes').then(
+                        (m) => m.inscription_routes,
+                    ),
+            },
+            // {...},
+            // ...
+            // recovery link should redirect to /inscription/reference
+            { path: ':reference', redirectTo: 'inscription/:reference', pathMatch: 'full' },
+            { path: '', redirectTo: 'welcome', pathMatch: 'full' },
+            { path: '404', component: FoehnNotfoundComponent },
+            { path: '**', redirectTo: '/404', pathMatch: 'full' },
+        ],
+    },
+];
+```
+
+> 💡 On charge donc `welcome.routes.ts` (et non plus `welcome.module.ts`) :
+> `loadChildren: () => import('./modules/welcome/welcome.routes').then((m) => m.welcome_routes)`
+> au lieu de `import('./modules/welcome/welcome.module').then((m) => m.WelcomeModule)`.
+
+`welcome.routes.ts`
+
+```ts
+export const welcome_routes: Routes = [
+    {
+        path: '',
+        children: [{ path: '', component: WelcomePageComponent }],
+    },
+];
+```
+
+`inscription.routes.ts`
+
+```ts
+export const inscription_routes: Routes = [
+    {
+        path: '',
+        data: { root: true },
+        children: [
+            { path: '', component: PageOneComponent, canActivate: [GesdemLoaderGuard] },
+            { path: 'erreur', component: GesdemErrorComponent },
+            {
+                path: ':reference',
+                children: [
+                    { path: 'page-1', component: PageOneComponent, data: { order: 1 } },
+                    // {...},
+                    // ...
+                    { path: 'erreur', component: GesdemErrorComponent },
+                    { path: '404', component: FoehnNotfoundComponent },
+                    { path: '', redirectTo: 'page-1', pathMatch: 'full' },
+                ],
+                canActivate: [GesdemLoaderGuard],
+            },
+        ],
+    },
+];
+```
+
+> 💡 Vous pouvez aussi charger paresseusement (`lazy-load`) un composant :
+>
+> ```ts
+> { path: 'list', loadComponent: () => import('./demande-list-page/demande-list-page.component').then((m) => m.DemandeListPageComponent) },
+> ```
+
+## Création d'un composant réutilisable
+
+> ℹ️ Créer un composant réutilisable en Angular n'est pas difficile mais pour qu'il soit adapté à
+> prestations-ng, c'est une autre affaire. Il va falloir respecter certaines règles, sans quoi, ça ne
+> fonctionnera pas correctement.
+
+### Exemple avec foehn-input-date de prestations-ng
+
+Votre composant doit :
+
+1. `selector` devrait commencer par `"app-..."` pour éviter d'éventuels conflits de nommage
+2. avoir un `providers`
+3. étendre `FoehnInputComponent` et vous devez lui préciser votre modèle de données
+4. répartir les attributs de votre modèle de données dans des variables publiques utilisées dans
+   votre HTML
+5. implémenter une fonction `update` (ici ce sera `updateDate`) qui fera appel à `updateNgModel` pour
+   maintenir la synchronisation de votre modèle de données avec votre page
+6. implémenter une fonction `handleUserInput` qui fera appel à `handleChange` pour continuer à
+   notifier le parent des changements de comportement de votre composant
+7. implémenter une fonction `onModelChange` qui vous permettra d'initialiser correctement les
+   variables publiques correspondant à votre modèle
+8. implémenter une fonction `getValidValue` afin de reconstruire votre modèle de données avant de le
+   retransmettre à votre page et retourner `null` si tous les attributs de votre objet sont vides (ça
+   c'est pour que Java soit content)
+
+> 🚨 Points **standalone / signals** à respecter :
+>
+> - **Pas de `multi: true`** dans le `providers` (retiré depuis la migration standalone).
+> - Les `imports` du composant se déclarent **directement** dans le décorateur `@Component`. Chaque
+>   composant charge ce dont il a besoin (voir `foehn-input-date` dans ce projet).
+
+`input-date.component.ts`
+
+```ts
+import { Component, forwardRef } from '@angular/core';
+
+import { FoehnInputComponent } from '../foehn-input/foehn-input.component';
+import { FoehnInputNumberComponent } from '../foehn-input/foehn-input-number.component';
+import { FoehnValidationAlertsComponent } from '../foehn-validation-alerts/foehn-validation-alerts.component';
+import { SdkDictionaryPipe } from '../sdk-dictionary/sdk-dictionary.pipe';
+
+@Component({
+    // point (1) : dans votre prestation, le selector sera plutôt 'app-...'
+    selector: 'app-input-date',
+    templateUrl: './input-date.component.html',
+    // point (2)
+    providers: [
+        {
+            provide: FoehnInputComponent,
+            useExisting: forwardRef(() => InputDateComponent),
+            // ⚠️ plus de `multi: true` en standalone
+        },
+    ],
+    // les imports se déclarent directement ici : chaque composant charge ce dont il a besoin
+    imports: [
+        FoehnValidationAlertsComponent,
+        FoehnInputNumberComponent,
+        SdkDictionaryPipe,
+    ],
+})
+export class InputDateComponent extends FoehnInputComponent<number[]> {
+    // point (3) : extends FoehnInputComponent<number[]>
+
+    // point (4) : les attributs de votre modèle répartis en variables publiques
+    day: string;
+    month: string;
+    year: string;
+
+    // point (5)
+    updateDate(): void {
+        const validValue = this.getValidValue();
+        if (typeof validValue !== 'undefined') {
+            this.updateNgModel(validValue);
+        }
+    }
+
+    // point (6)
+    handleUserInput(): void {
+        const validValue = this.getValidValue();
+        if (typeof validValue !== 'undefined') {
+            this.handleChange(validValue);
+        }
+    }
+
+    // point (7)
+    override onModelChange(value: number[]): void {
+        if (value && value.length > 2) {
+            this.year = this.toString(value[0]);
+            this.month = this.toString(value[1]);
+            this.day = this.toString(value[2]);
+        } else if (!value) {
+            this.year = null;
+            this.month = null;
+            this.day = null;
+        }
+    }
+
+    // point (8)
+    getValidValue(): number[] | null | undefined {
+        if (this.isEmpty(this.day) && this.isEmpty(this.month) && this.isEmpty(this.year)) {
+            if (this.model_ !== undefined) {
+                return null;
+            }
+
+            return undefined;
+        }
+
+        return [this.toNumber(this.year), this.toNumber(this.month), this.toNumber(this.day)];
+    }
+
+    // ...code
+}
+```
+
+Chaque `foehn-input-*` utilisé dans votre vue doit :
+
+1. avoir un `id` qui concatène l'appel à la fonction `buildId()` et le nom de l'attribut de votre objet
+2. avoir un `name` qui concatène l'input **signal** `name()` et le nom de l'attribut de votre objet
+3. avoir un `label`
+4. utiliser votre variable publique comme model en double-binding (banana in the box)
+5. faire appel à `updateDate()` lors du déclenchement de l'événement `(modelChange)`
+6. faire appel à `handleUserInput()` lors du déclenchement de l'événement `(userInput)`
+
+> 💡 `name` est désormais un **input signal**. On l'invoque : `name() + '_day'` (et non plus
+> `name + '_day'`).
+
+`input-date.component.html`
+
+```html
+<foehn-input-number
+    [id]="buildId() + '_day'"
+    [name]="name() + '_day'"
+    [label]="'input-date.day.label' | fromDictionary"
+    [(model)]="day"
+    (modelChange)="updateDate()"
+    (userInput)="handleUserInput()"
+    [required]="required()"
+    [hideNotRequiredExtraLabel]="true"
+    [maxlength]="2"
+/>
+<!-- ... -->
+<foehn-input-number
+    [id]="buildId() + '_month'"
+    [name]="name() + '_month'"
+    [label]="'input-date.month.label' | fromDictionary"
+    [(model)]="month"
+    (modelChange)="updateDate()"
+    (userInput)="handleUserInput()"
+    [required]="required()"
+    [hideNotRequiredExtraLabel]="true"
+    [maxlength]="2"
+/>
+<!-- ... -->
+<foehn-input-number
+    [id]="buildId() + '_year'"
+    [name]="name() + '_year'"
+    [label]="'input-date.year.label' | fromDictionary"
+    [(model)]="year"
+    (modelChange)="updateDate()"
+    (userInput)="handleUserInput()"
+    [required]="required()"
+    [hideNotRequiredExtraLabel]="true"
+    [maxlength]="4"
+/>
+```
+
+### Afficher la validation globale du composant
+
+- Il faut ajouter dans la partie HTML de votre composant le code décrit ci-dessous
+- Remonter une erreur correspondant au `name` de votre composant lorsque celui-ci est utilisé dans
+  votre page de formulaire.
+
+> 💡 Points **signals** à noter dans ce template :
+>
+> - `@if` remplace `*ngIf` et les attributs du composant sont des signaux : on les invoque
+>   (`label()`, `required()`, `isLabelSrOnly()`, `hideNotRequiredExtraLabel()`, `helpText()`).
+> - `[ngClass]` est remplacé par des bindings `[class.xxx]="..."`.
+
+```html
+<!-- (obligatoire) Affichera une barre verticale rouge sur l'entier du composant -->
+<div
+    class="form-group"
+    [class.has-danger]="hasErrorsToDisplay()"
+    [class.vd-form-group-danger]="hasErrorsToDisplay()"
+    [attr.id]="buildId('Container')"
+    tabindex="-1"
+>
+    <!-- (obligatoire) Permet de regrouper vos champs pour une validation globale -->
+    <fieldset
+        [attr.aria-describedby]="getDescribedBy()"
+        [attr.aria-invalid]="hasErrorsToDisplay() || null"
+    >
+        <!-- (facultatif) Seulement si vous souhaitez afficher un label/legend global à votre composant -->
+        @if (!!label()) {
+            <legend
+                [class.visually-hidden]="isLabelSrOnly()"
+                [class.vd-p]="!isLabelSrOnly()"
+            >
+                <span [innerHTML]="label()"></span>
+                @if (!required() && !hideNotRequiredExtraLabel()) {
+                    <span aria-hidden="true">{{ 'foehn-input.optional' | fromDictionary }}</span>
+                }
+            </legend>
+        }
+
+        <!-- (obligatoire) -->
+        <foehn-validation-alerts [component]="this" />
+
+        <!-- (facultatif) Seulement si vous souhaitez pouvoir afficher un helpText global au composant -->
+        @if (helpText()) {
+            <small
+                [attr.id]="buildId() + 'Help'"
+                class="text-secondary"
+                [innerHTML]="helpText()"
+            ></small>
+        }
+
+        <!-- ...vos foehn-input-* ici -->
+    </fieldset>
+</div>
+```
+
+### Éviter des problèmes d'affichage d'erreurs dans une boucle `@for`
+
+> ⚠️ Ne pas oublier de mettre un `track` avec un identifiant unique dans la boucle `@for` sinon la
+> validation ne s'affichera pas. Quand un identifiant unique tel que `id` n'est pas possible, tracker
+> par objet ou, en dernier recours, `track $index`.
+
+> ℹ️ Dans une boucle `@for` d'Angular avec un composant `FoehnInputComponent`, si vous validez votre
+> formulaire, les erreurs remontées sont synchronisées avec l'index de vos composants répétés dans la
+> boucle.
+>
+> **Scénario :** Dans votre liste, lorsque vous supprimez un composant qui contient des erreurs à
+> l'index 0 (par ex.) et que le composant suivant (index 1) n'a pas d'erreur ou pas les mêmes
+> erreurs, alors ce dernier se retrouve avec les erreurs du composant fraîchement supprimé à
+> l'index 0.
+>
+> **Explication :** Ce phénomène est dû au fait que les erreurs remontées par GESDEM ne se
+> rafraîchissent que lors de la demande de sauvegarde des données. Du coup, le composant supprimé à
+> l'index 0 est remplacé par celui à l'index 1 mais les erreurs à l'index 0, elles, existent toujours
+> et se reportent donc sur le composant venant de l'index 1.
+
+Voici la bonne pratique à mettre en place pour palier à ces problèmes d'affichage d'erreurs dans une
+boucle `@for`.
+
+Lorsque vous supprimez un élément dans votre liste, vous devez appeler une méthode se trouvant dans
+votre `AbstractPageComponent`. Cette méthode contiendra le code suivant :
+
+```ts
+/*
+ * if an inventory item that was in error is removed, this prevents the error to be displayed
+ * to the next item that has taken it's index
+ */
+this._gesdemService.validate(this.form).pipe(first()).subscribe();
+```
+
+Voici un exemple de page de formulaire contenant cette méthode (1) :
+
+> 💡 Plus de `constructor` : on fait de l'**inject**. Les dépendances de `AbstractPageComponent`
+> (dont `_dictionaryService` et `_gesdemService`) sont déjà injectées dans la classe abstraite. Pour
+> vos propres dépendances, utilisez `inject()`.
+
+```ts
+@Component({
+    templateUrl: './votre-page.component.html',
+    imports: [
+        // ... vos composants foehn-*
+    ],
+})
+export class VotrePageComponent extends AbstractPageComponent<BusinessForm> implements OnInit {
+    // vos propres dépendances : inject() au lieu du constructor
+    private readonly metaService = inject(MetaService);
+
+    ngOnInit(): void {
+        super.ngOnInit();
+        this.setPageTitle(this._dictionaryService.getKeySync('votre-page.title'));
+    }
+
+    newForm(): BusinessForm {
+        return new BusinessForm();
+    }
+
+    handleRemovedVehicule(): void {
+        // (1)
+        /*
+         * if an inventory item that was in error is removed, this prevents the error to be displayed
+         * to the next item that has taken it's index
+         */
+        this._gesdemService.validate(this.form).pipe(first()).subscribe();
+    }
+}
+```
+
+Il ne tient qu'à vous de décider comment appeler cette méthode lors de la suppression de l'élément de
+votre liste.
+
+Voici une manière élégante de gérer vos listes d'éléments :
+
+- Structure des dossiers et fichiers
+
+```text
+demande-page/
+├── vehicules-list/
+│   ├── vehicule-item/
+│   │   ├── vehicule-item.component.css
+│   │   ├── vehicule-item.component.html
+│   │   └── vehicule-item.component.ts
+│   ├── vehicules-list.component.html
+│   └── vehicules-list.component.ts
+├── demande-page.component.html
+└── demande-page.component.ts
+```
+
+**vehicule-item**
+
+`vehicule-item.component.html` contient le bouton pour la suppression de l'élément dans la liste (1).
+
+```html
+<div
+    class="form-group clearable-input-form-group"
+    [class.has-danger]="hasErrorsToDisplay()"
+    [class.vd-form-group-danger]="hasErrorsToDisplay()"
+    [attr.id]="buildId('Container')"
+    tabindex="-1"
+>
+    <foehn-validation-alerts [component]="this" />
+
+    <div class="row d-flex align-items-end vehicule-infos">
+        <!-- ... vos composants foehn-input-* -->
+
+        <div class="col-md-2 mt-md-0 mt-xs-2">
+            <button class="btn btn-danger" (click)="removeVehicule()">
+                <!-- (1) -->
+                {{ 'demande-page.vehicule-remove' | fromDictionary }}
+            </button>
+        </div>
+    </div>
+</div>
+```
+
+`vehicule-item.component.ts` contient la fonction de suppression qui va remonter l'événement à son
+parent (la liste des éléments).
+
+> 💡 `@Output() + EventEmitter` sont remplacés par la fonction `output()`.
+
+```ts
+@Component({
+    selector: 'app-vehicule-item',
+    templateUrl: './vehicule-item.component.html',
+    providers: [
+        {
+            provide: FoehnInputComponent,
+            useExisting: forwardRef(() => VehiculeItemComponent),
+        },
+    ],
+    imports: [
+        FoehnValidationAlertsComponent,
+        // ... vos foehn-input-*
+        SdkDictionaryPipe,
+    ],
+})
+export class VehiculeItemComponent extends FoehnInputComponent<Vehicule> {
+    readonly removedVehicule = output<void>();
+
+    removeVehicule(): void {
+        this.removedVehicule.emit();
+    }
+
+    // ...code
+}
+```
+
+**vehicules-list**
+
+`vehicules-list.component.html` contient votre boucle `@for` (1) et votre composant répétable (2) qui
+devra lui aussi remonter l'événement.
+
+> ⚠️ Dans la boucle `@for` ne pas oublier de mettre un `track` (identifiant unique) sinon la
+> validation ne s'affichera pas. Ici nous trackons par exemple avec `vehicule.id`.
+
+```html
+<div
+    class="form-group clearable-input-form-group"
+    [class.has-danger]="hasErrorsToDisplay()"
+    [class.vd-form-group-danger]="hasErrorsToDisplay()"
+    [attr.id]="buildId('Container')"
+    tabindex="-1"
+>
+    @if (label() && type() !== 'hidden') {
+        <label
+            [attr.for]="buildChildId()"
+            [class]="'form-label ' + (isLabelSrOnly() ? 'visually-hidden' : (labelStyleModifier() ?? ''))"
+        >
+            {{ label() }}
+            @if (!required() && !hideNotRequiredExtraLabel()) {
+                <span aria-hidden="true">{{ 'foehn-input.optional' | fromDictionary }}</span>
+            }
+        </label>
+    }
+
+    <foehn-validation-alerts [component]="this" />
+
+    @if (helpText()) {
+        <small
+            [attr.id]="buildChildId() + 'Help'"
+            class="form-text text-secondary"
+            [innerHTML]="helpText()"
+        ></small>
+    }
+
+    <!-- (1) votre boucle @for + track (identifiant unique) -->
+    @for (vehicule of vehicules; track vehicule.id; let i = $index) {
+        <!-- (2) votre composant réutilisable -->
+        <app-vehicule-item
+            [name]="name() + '[' + i + ']'"
+            [(model)]="vehicule"
+            (modelChange)="updateVehiculesList($event, i)"
+            (userInput)="handleUserInput($event, i)"
+            (removedVehicule)="handleRemovedVehicule(i)"
+        />
+    }
+
+    <button class="btn btn-primary mt-2" (click)="addVehicule()">
+        {{ 'demande-page.vehicule-add' | fromDictionary }}
+    </button>
+</div>
+```
+
+> 💡 Le `name` est un input signal : `[name]="name() + '[' + i + ']'"` (et non plus
+> `[name]="name + '[' + i + ']'"`).
+
+`vehicules-list.component.ts` remonte à son tour l'événement (1) au parent (`AbstractPageComponent`)
+ainsi que supprimer l'élément de la liste (2). C'est aussi ici que vous pouvez gérer l'ajout d'un
+élément (3).
+
+```ts
+@Component({
+    selector: 'app-vehicules-list',
+    templateUrl: './vehicules-list.component.html',
+    providers: [
+        {
+            provide: FoehnInputComponent,
+            useExisting: forwardRef(() => VehiculesListComponent),
+        },
+    ],
+    imports: [
+        VehiculeItemComponent,
+        FoehnValidationAlertsComponent,
+        SdkDictionaryPipe,
+    ],
+})
+export class VehiculesListComponent extends FoehnInputComponent<Vehicule[]> {
+    readonly removedVehicule = output<void>(); // (1) événement à remonter au parent
+
+    vehicules: Vehicule[] = []; // Tableau contenant vos éléments répétables
+
+    handleRemovedVehicule(index: number): void {
+        // (2) votre fonction de suppression de l'élément ainsi que la transmission de l'évènement
+        this.vehicules.splice(index, 1); // suppression de l'élément
+        this.getValidValueAndUpdateNgModel(); // Mise à jour de votre modèle
+        this.removedVehicule.emit(); // (1) on remonte l'évènement
+    }
+
+    addVehicule(): void {
+        // (3) Gestion de l'ajout d'un élément
+        // ...code
+    }
+}
+```
+
+> 💡 Plus besoin de définir une `trackByFn` dédiée : la nouvelle syntaxe `@for` utilise directement
+> l'expression `track` (ici `vehicule.id`).
+
+**demande-page**
+
+`demande-page.component.html` utilisera votre composant de liste de véhicule (1) et écoutera pour
+l'événement de suppression (2).
+
+```html
+<foehn-form>
+    <!-- ... -->
+    <h2>{{ 'demande-page.vehicules' | fromDictionary }}</h2>
+
+    <app-vehicules-list
+        [(model)]="form.vehicules"
+        name="vehicules"
+        [label]="'demande-page.vehicules-list' | fromDictionary"
+        [required]="true"
+        (removedVehicule)="handleRemovedVehicule()"
+    />
+    <!-- (1) Utilisation de votre liste - (2) Appel de la méthode qui sauvegardera les données dans GESDEM afin de rafraîchir les erreurs -->
+
+    <foehn-navigation id="navigation" (onPrevious)="previous()" (onNext)="send()" />
+</foehn-form>
+```
+
+`demande-page.component.ts` se chargera de l'appel à GESDEM afin de re-générer les erreurs du
+formulaire et ainsi rafraîchir l'index.
+
+```ts
+@Component({
+    // ...
+})
+export class DemandePageComponent extends AbstractPageComponent<BusinessForm> implements OnInit {
+    // ...code
+
+    handleRemovedVehicule(): void {
+        /*
+         * if an inventory item that was in error is removed, this prevents the error to be displayed
+         * to the next item that has taken it's index
+         */
+        this._gesdemService.save(this.form).pipe(first()).subscribe();
+    }
+}
+```
+
+## Validation du formulaire
+
+> ℹ️ Lors de la sauvegarde de votre formulaire dans GESDEM, l'`AbstractPageComponent` gère pour vous
+> l'affichage éventuel des erreurs.
+>
+> Si par contre vous souhaitez sauvegarder les données ailleurs que dans GESDEM, vous serez confronté
+> à la gestion manuelle de l'affichage des erreurs.
+
+### Gestion standard
+
+> ℹ️ Lors de l'enregistrement de vos données dans GESDEM, l'affichage des erreurs est automatiquement
+> géré pour vous. Cependant, vous devez impérativement respecter certaines règles.
+
+Prenons un exemple de modèle simple côté front à deux niveaux de profondeur :
+
+`identification.ts`
+
+```ts
+export class Identification {
+    firstName: string;
+    lastName: string;
+}
+```
+
+`business-form.ts`
+
+```ts
+export class BusinessForm {
+    acceptCookies: boolean;
+    identification: Identification = new Identification();
+}
+```
+
+> ⚠️ Le modèle ci-dessus devra impérativement être reflété dans le `name` de vos composants
+> `foehn-input-*` de votre page.
+
+`page-1.html`
+
+```html
+<foehn-input-text
+    [(model)]="form.identification.firstName"
+    name="identification.firstName"
+/>
+<!-- 2 niveaux de profondeur -->
+
+<foehn-input-text
+    [(model)]="form.identification.lastName"
+    name="identification.lastName"
+/>
+
+<foehn-boolean-checkbox
+    [(model)]="form.acceptCookies"
+    name="acceptCookies"
+/>
+<!-- 1 niveau de profondeur -->
+```
+
+- Côté back-end, vous pouvez gérer vos erreurs grâce aux annotations (`@NotEmpty`, `@NotNull`, ...),
+  et **prestations-be** fera le reste pour vous.
+- Si vous souhaitez remonter une erreur spécifique à un champ de votre formulaire, voici la syntaxe :
+
+```java
+new AbstractSdkController.FormError("identification.lastName", "ErrorCodeHere", "Le nom est obligatoire si vous ne spécifiez pas de prénom")
+```
+
+> ⚠️ Le nom de l'erreur doit impérativement correspondre au nom de votre composant dans votre page
+> HTML.
+
+### Gestion manuelle
+
+#### Back-end
+
+Côté back-end JAVA, le serveur devra retourner un objet contenant les erreurs du formulaire afin
+d'être compatible avec prestations-ng.
+
+```java
+@Getter
+@Setter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class PostResponse<T> {
+
+    private T dto;
+
+    @Builder.Default
+    private List<AbstractSdkController.FormError> errors = new ArrayList<>();
+    // AbstractSdkController.FormError vient de prestations-be qui est la partie backend de prestations-ng
+}
+```
+
+Ensuite, ajoutez vos erreurs dans votre modèle avant de le retourner au front-end :
+
+```java
+List<AbstractSdkController.FormError> errors = new ArrayList<>();
+errors.add(new AbstractSdkController.FormError("identification.lastName", "ErrorCodeHere", "Le nom est obligatoire si vous ne spécifiez pas de prénom"));
+
+PostResponse.<MyObject>builder().dto(myObject).errors(errors).build();
+```
+
+#### Front-end
+
+Côté front-end, comme la validation standard, les noms de vos composants `foehn-input-*` de votre
+page HTML et le nom de vos erreurs devront correspondre.
+
+```html
+<foehn-input-text
+    [(model)]="form.identification.lastName"
+    name="identification.lastName"
+/>
+```
+
+> ⚠️ Au retour de la sauvegarde de vos données, vous allez devoir déclencher manuellement la
+> validation.
+
+1. Dans votre `page.ts`, créez une fonction `handleValidationErrors` pour gérer l'affichage des
+   erreurs.
+2. Cette fonction sera appelée au retour du back-end.
+
+> 💡 Point **signals** : plus de `@ViewChild('formWithModels')`. Pour utiliser un composant dans le
+> TypeScript, on utilise un **signal** `viewChild(...)`. On accède ensuite à l'instance en l'invoquant :
+> `this.formWithModels()`.
+
+`page.ts`
+
+```ts
+import {
+    ErrorTemplate,
+    GrowlBrokerService,
+    GrowlType,
+    ValidationHandlerService,
+} from '@dsivd/prestations-ng';
+
+@Component({
+    // ...
+})
+export class ... extends AbstractPageComponent<YOUR_MODEL> implements OnInit {
+    // point (7 des signaux) : un signal viewChild au lieu de @ViewChild
+    readonly formWithModels = viewChild(FoehnFormComponent);
+
+    // vos propres dépendances via inject()
+    private readonly httpClient = inject(HttpClient);
+
+    ngOnInit(): void {
+        super.ngOnInit();
+        // Activer l'affichage des erreurs
+        this._validationHandlerService.shouldDisplayErrors(true);
+    }
+
+    // Fonction de sauvegarde
+    save(): void {
+        // Activer l'affichage des erreurs
+        this._validationHandlerService.shouldDisplayErrors(true);
+        // Appel au back pour faire votre validation
+        this.httpClient
+            .post<PostResponse>('api_url_ici', votre_objet)
+            .subscribe((response: PostResponse) => {
+                if (!response.errors.length) {
+                    // On prévient l'utilisateur que tout s'est bien passé
+                    this._growlService.addWithType(
+                        GrowlType.SUCCESS,
+                        'Enregistrement effectué avec succès',
+                    );
+                }
+                // Gestion des erreurs au retour du back-end
+                this.handleValidationErrors(response.errors); // point (2)
+            });
+    }
+
+    // Affichage des erreurs
+    private handleValidationErrors(errors: ErrorTemplate[]): void {
+        // point (1)
+        const form = this.formWithModels();
+        // Need to markAsUntouched and markAsPristine so error can be shown
+        form.reset();
+        // Feed errors to validation service
+        this._validationHandlerService.updateErrors(errors);
+        // Manually set the focus. On a real application the abstract-page-controller will do it.
+        form.focusErrorSummary();
+    }
+}
+```
+
+`page.html`
+
+```html
+<foehn-form>
+    <!-- ... vos composants foehn-input-* -->
+</foehn-form>
+```
+
+## Validation manuelle d'un composant
+
+### Cacher une erreur
+
+> ✅ Utiliser la fonction `markAsDirty()` permet de simuler une interaction avec le composant.
+>
+> ℹ️ Permet de cacher l'erreur d'un composant foehn-input en erreur.
+
+### Afficher une erreur
+
+> ✅ Utiliser la fonction `markAsPristine()` remet le composant dans son état d'origine comme si
+> aucune interaction n'avait été effectuée.
+>
+> ℹ️ Permet d'afficher l'erreur d'un composant foehn-input en erreur.