@starterlib/ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starterlib/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Bibliotheque de composants st-* du socle frontal starter, sur CDK et Aria.",
   "license": "UNLICENSED",
   "sideEffects": false,
@@ -22,10 +22,11 @@
     "@angular/core": "^22.1.0",
     "@angular/common": "^22.1.0",
     "@angular/router": "^22.1.0",
+    "@angular/forms": "^22.1.0",
     "@angular/cdk": "^22.1.0",
     "@angular/aria": "^22.1.0",
-    "@starterlib/tokens": "^0.3.0",
-    "@starterlib/util": "^0.3.0"
+    "@starterlib/tokens": "^0.4.0",
+    "@starterlib/util": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@angular/cdk": {
@@ -33,6 +34,9 @@
     },
     "@angular/aria": {
       "optional": true
+    },
+    "@angular/forms": {
+      "optional": true
     }
   },
   "module": "fesm2022/starterlib-ui.mjs",
@@ -45,6 +49,10 @@
       "types": "./types/starterlib-ui.d.ts",
       "default": "./fesm2022/starterlib-ui.mjs"
     },
+    "./formulaires": {
+      "types": "./types/starterlib-ui-formulaires.d.ts",
+      "default": "./fesm2022/starterlib-ui-formulaires.mjs"
+    },
     "./interactions": {
       "types": "./types/starterlib-ui-interactions.d.ts",
       "default": "./fesm2022/starterlib-ui-interactions.mjs"

package/types/starterlib-ui-formulaires.d.ts

@@ -0,0 +1,198 @@
+import * as _starterlib_ui from '@starterlib/ui';
+import { ContratDeChamp, ErreurAffichable } from '@starterlib/ui';
+import * as _angular_forms_signals from '@angular/forms/signals';
+import { FormValueControl } from '@angular/forms/signals';
+import * as _angular_core from '@angular/core';
+import { DateIso, PlageDeDates } from '@starterlib/util';
+
+/**
+ * Montant, en UNITES MINEURES : `123456n` pour 1 234,56 EUR.
+ *
+ * ```html
+ * <st-amount-field libelle="Montant du virement" devise="EUR" [formField]="virement.montant" />
+ * ```
+ *
+ * ⚠️ **Jamais un nombre a virgule flottante** (SEC-8) : le modele est un `bigint`,
+ * lu chiffre par chiffre par `lireMontant`. `0,1 + 0,2` ne fait pas `0,3`, et
+ * 1 234,56 EUR ne doit pas devenir 1 234,5599999.
+ *
+ * ⚠️ **Un texte ambigu est refuse, jamais devine.** « 1.250 » en francais serait
+ * mille deux cent cinquante ou un virgule vingt-cinq : le champ dit l'erreur et
+ * garde le texte, plutot que d'envoyer un montant mille fois trop grand. Une
+ * saisie illisible laisse le MODELE inchange et rend le formulaire invalide, par
+ * `transformedValue` : il ne part pas avec l'ancien montant.
+ *
+ * Le groupement « 1 234,56 » s'applique a la sortie du champ, jamais pendant la
+ * frappe. `type="text"` et `inputmode="decimal"` : `type="number"` accepte
+ * « 1e5 », change la valeur a la molette, et ignore la virgule selon le navigateur.
+ *
+ * Les bornes — montant minimal, plafond — sont des regles du schema, en unites
+ * mineures ; le serveur les revalide (SEC-5).
+ */
+declare class StAmountField extends ContratDeChamp implements FormValueControl<bigint | null> {
+    private readonly libelles;
+    private readonly locale;
+    readonly value: _angular_core.ModelSignal<bigint | null>;
+    /** Code ISO 4217. Fixe l'echelle : 2 decimales en euros, 0 en yens. */
+    readonly devise: _angular_core.InputSignal<string>;
+    /** `transaction-amount` pour un paiement. */
+    readonly autocomplete: _angular_core.InputSignal<string | null>;
+    /**
+     * Quitte au moins une fois. Relie a un formulaire, `touched` le dit ; employe
+     * seul, rien ne le dirait, et une saisie illisible ne s'afficherait jamais.
+     */
+    protected readonly quitte: _angular_core.WritableSignal<boolean>;
+    protected readonly saisie: _angular_forms_signals.TransformedValueSignal<string>;
+    protected readonly erreursAffichees: _angular_core.Signal<readonly _starterlib_ui.ErreurAffichable[]>;
+    /** Symbole affiche a cote du champ ; le nom de la devise, lui, est lu. */
+    protected readonly symbole: _angular_core.Signal<string>;
+    protected readonly deviseLue: _angular_core.Signal<string>;
+    protected surSaisie(evenement: Event): void;
+    protected aLaSortie(): void;
+    private formater;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StAmountField, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StAmountField, "st-amount-field", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "devise": { "alias": "devise"; "required": true; "isSignal": true; }; "autocomplete": { "alias": "autocomplete"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+/**
+ * Date calendaire : un champ texte, et un calendrier pour qui prefere choisir.
+ *
+ * ```html
+ * <st-date-field libelle="Date de naissance" autocomplete="bday" [dateMax]="aujourdHui"
+ *   [formField]="profil.naissance" />
+ * <!-- schema : validate(chemin.naissance, ({ value }) => erreurDate(value(), { max: aujourdHui })) -->
+ * ```
+ *
+ * Le modele est une date ISO — `2026-09-17` — ou `null`, jamais un objet `Date` :
+ * une date calendaire n'a ni heure ni fuseau.
+ *
+ * ⚠️ **Un champ texte d'abord** (decision D7 de l'audit de la vague 3). Le champ
+ * natif `type="date"` affiche son format dans la langue du NAVIGATEUR : il ne
+ * bascule pas quand l'application change de langue. Ici, le format attendu —
+ * `jj/mm/aaaa` ou `mm/dd/yyyy` — suit la langue courante, et il est dit en aide.
+ *
+ * ⚠️ **Le calendrier est une aide, pas la seule voie** : une date de naissance
+ * se tape plus vite qu'elle ne se cherche mois par mois. Il s'ouvre sous le champ,
+ * dans le flux de la page : pas de surcouche a positionner, rien de rogne dans
+ * un dialogue, et le CDK n'entre pas dans les formulaires.
+ *
+ * Une date illisible ou inexistante — « 31/02/2026 » — garde le texte, laisse le
+ * modele inchange et rend le formulaire invalide.
+ */
+declare class StDateField extends ContratDeChamp implements FormValueControl<DateIso | null> {
+    protected readonly libelles: _angular_core.Signal<_starterlib_ui.LibellesUi>;
+    private readonly locale;
+    private readonly element;
+    private readonly injecteur;
+    readonly value: _angular_core.ModelSignal<string | null>;
+    /** Bornes du calendrier. Les memes que celles du schema : voir `erreurDate`. */
+    readonly dateMin: _angular_core.InputSignal<string | null>;
+    readonly dateMax: _angular_core.InputSignal<string | null>;
+    /** `bday` pour une date de naissance. */
+    readonly autocomplete: _angular_core.InputSignal<string | null>;
+    protected readonly ouvert: _angular_core.WritableSignal<boolean>;
+    protected readonly identifiantCalendrier: string;
+    private readonly calendrier;
+    private readonly bouton;
+    /**
+     * Quitte au moins une fois. Relie a un formulaire, `touched` le dit ; employe
+     * seul, rien ne le dirait, et une saisie illisible ne s'afficherait jamais.
+     */
+    protected readonly quitte: _angular_core.WritableSignal<boolean>;
+    protected readonly saisie: _angular_forms_signals.TransformedValueSignal<string>;
+    protected readonly aideLue: _angular_core.Signal<string>;
+    protected readonly erreursAffichees: _angular_core.Signal<readonly _starterlib_ui.ErreurAffichable[]>;
+    protected surSaisie(evenement: Event): void;
+    protected aLaSortieDuChamp(): void;
+    protected basculer(): void;
+    protected choisir(date: DateIso): void;
+    /** Echap rend le focus au bouton qui a ouvert le calendrier. */
+    protected fermer(rendreLeFocus: boolean): void;
+    protected aLaSortieDuComposant(evenement: FocusEvent): void;
+    private formater;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StDateField, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StDateField, "st-date-field", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "dateMin": { "alias": "dateMin"; "required": false; "isSignal": true; }; "dateMax": { "alias": "dateMax"; "required": false; "isSignal": true; }; "autocomplete": { "alias": "autocomplete"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+type Partie = 'debut' | 'fin';
+interface SaisieDePlage {
+    readonly debut: string;
+    readonly fin: string;
+}
+/**
+ * Plage de dates : un debut, une fin, dans un groupe nomme par sa question.
+ *
+ * ```html
+ * <st-date-range libelle="Periode du sejour" [formField]="reservation.sejour" />
+ * <!-- schema : validate(chemin.sejour, ({ value }) => erreurPlageDeDates(value())) -->
+ * ```
+ *
+ * Deux champs texte etiquetes — « Date de debut », « Date de fin » — dans un
+ * `fieldset` dont la legende est le `libelle` : chacun se lit avec la question.
+ * Chaque champ a son calendrier ; celui de la fin s'ouvre au mois du debut et
+ * refuse les jours qui le precedent.
+ *
+ * ⚠️ **Une erreur dit QUELLE date corriger** : « Date de fin : saisissez une date
+ * qui existe… ». Sans le nom de la partie, deux messages identiques ne disent pas
+ * lequel des champs est faux. L'erreur de lecture marque aussi son champ
+ * `aria-invalid`, et lui seul.
+ *
+ * L'obligation d'une borne est une regle du schema : `required` ne sait pas ce
+ * qu'est une plage « vide ».
+ */
+declare class StDateRange extends ContratDeChamp implements FormValueControl<PlageDeDates> {
+    protected readonly libelles: _angular_core.Signal<_starterlib_ui.LibellesUi>;
+    private readonly locale;
+    private readonly element;
+    private readonly injecteur;
+    readonly value: _angular_core.ModelSignal<PlageDeDates>;
+    readonly dateMin: _angular_core.InputSignal<string | null>;
+    readonly dateMax: _angular_core.InputSignal<string | null>;
+    /** Etiquettes des deux champs. Par defaut : « Date de debut », « Date de fin ». */
+    readonly libelleDebut: _angular_core.InputSignal<string | null>;
+    readonly libelleFin: _angular_core.InputSignal<string | null>;
+    protected readonly parties: readonly Partie[];
+    protected readonly ouvert: _angular_core.WritableSignal<Partie | null>;
+    protected readonly identifiants: {
+        readonly debut: `${string}-debut`;
+        readonly fin: `${string}-fin`;
+        readonly calendrier: `${string}-calendrier`;
+    };
+    private readonly calendrier;
+    /**
+     * Quitte au moins une fois. Relie a un formulaire, `touched` le dit ; employe
+     * seul, rien ne le dirait, et une saisie illisible ne s'afficherait jamais.
+     */
+    protected readonly quitte: _angular_core.WritableSignal<boolean>;
+    protected readonly saisie: _angular_forms_signals.TransformedValueSignal<SaisieDePlage>;
+    protected readonly etiquettes: _angular_core.Signal<{
+        debut: string;
+        fin: string;
+    }>;
+    protected readonly aideLue: _angular_core.Signal<string>;
+    /** Chaque erreur prefixee de sa partie, dans la langue courante. */
+    protected readonly erreursAffichees: _angular_core.Signal<readonly ErreurAffichable[]>;
+    protected readonly invalide: _angular_core.Signal<{
+        debut: boolean;
+        fin: boolean;
+    }>;
+    protected surSaisie(partie: Partie, evenement: Event): void;
+    protected aLaSortieDuChamp(): void;
+    protected basculer(partie: Partie): void;
+    protected bornes(partie: Partie): {
+        min: DateIso | null;
+        max: DateIso | null;
+    };
+    protected choisir(partie: Partie, date: DateIso): void;
+    protected fermer(partie: Partie): void;
+    protected aLaSortieDuComposant(evenement: FocusEvent): void;
+    /** `null` : vide. `undefined` : illisible. */
+    private lirePartie;
+    private formater;
+    /** La partie visee : celle d'une erreur de lecture, la fin pour une plage inversee. */
+    private partieDe;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StDateRange, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StDateRange, "st-date-range", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "dateMin": { "alias": "dateMin"; "required": false; "isSignal": true; }; "dateMax": { "alias": "dateMax"; "required": false; "isSignal": true; }; "libelleDebut": { "alias": "libelleDebut"; "required": false; "isSignal": true; }; "libelleFin": { "alias": "libelleFin"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+export { StAmountField, StDateField, StDateRange };

package/types/starterlib-ui-interactions.d.ts

@@ -1,5 +1,8 @@
 import * as _angular_core from '@angular/core';
 import * as i1 from '@angular/aria/tabs';
+import * as _starterlib_ui from '@starterlib/ui';
+import { ControleDeSaisie, OptionDeListe, AnnonceLocale, ContratDeChamp } from '@starterlib/ui';
+import { FormValueControl } from '@angular/forms/signals';
 
 /** Un onglet, decrit par l'appelant. */
 interface Onglet {
@@ -158,5 +161,109 @@ declare class StSidenavToggle {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<StSidenavToggle, "[stSidenavToggle]", never, { "stSidenavToggle": { "alias": "stSidenavToggle"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { StSidenav, StSidenavToggle, StTabContent, StTabPanel, StTabs };
-export type { ActivationDOnglet, ModeDeNavigation, Onglet, OrientationDOnglets };
+/** `local` : le composant filtre `options`. `distant` : l'application filtre, sur `recherche`. */
+type FiltrageDeListe = 'local' | 'distant';
+/**
+ * Liste de choix a filtrer en tapant, sur `@angular/aria/combobox` et
+ * `@angular/aria/listbox`.
+ *
+ * ```html
+ * <st-combobox libelle="Beneficiaire" [options]="beneficiaires" [formField]="virement.beneficiaire" />
+ * <!-- liste servie par le serveur : -->
+ * <st-combobox libelle="Commune" filtrage="distant" [options]="communes()"
+ *   (recherche)="terme.set($event)" [formField]="adresse.commune" />
+ * ```
+ *
+ * Le modele est la VALEUR de l'option choisie, `''` sans choix. Le texte tape ne
+ * part jamais dans le modele : « Pari » n'est pas une commune.
+ *
+ * ⚠️ **Pour une longue liste seulement.** Sous une vingtaine d'options,
+ * `st-select` — natif — est plus sur, et plus rapide sur mobile.
+ *
+ * - La liste s'ouvre a la frappe et a la fleche bas ; Entree choisit, Echap
+ *   ferme. Le focus reste dans le champ (`aria-activedescendant`).
+ * - Le nombre de resultats s'annonce apres la frappe, une fois : le lecteur
+ *   d'ecran ne voit pas la liste se reduire.
+ * - ⚠️ **Quitter le champ sans choisir rend le texte du choix precedent.** Un
+ *   texte qui ne correspond a aucune option ne reste pas affiche comme s'il etait
+ *   retenu ; un champ vide, lui, retire le choix.
+ * - La liste est posee dans la couche superieure du navigateur (`popover`) par le
+ *   CDK : un dialogue ou un tableau defilant ne la rogne pas.
+ *
+ * ⚠️ En `distant`, `recherche` est emis a chaque frappe : a l'application de
+ * temporiser, et de ne pas mettre le terme dans l'adresse (SEC-6).
+ */
+declare class StCombobox extends ControleDeSaisie {
+    protected readonly libelles: _angular_core.Signal<_starterlib_ui.LibellesUi>;
+    private readonly element;
+    private readonly injecteur;
+    readonly options: _angular_core.InputSignal<readonly OptionDeListe[]>;
+    readonly filtrage: _angular_core.InputSignal<FiltrageDeListe>;
+    /** Texte tape, a chaque frappe. Sert au filtrage `distant`. */
+    readonly recherche: _angular_core.OutputEmitterRef<string>;
+    protected readonly annonce: AnnonceLocale;
+    protected readonly ouvert: _angular_core.WritableSignal<boolean>;
+    /** Texte du champ : le libelle du choix, tant que la personne ne tape pas. */
+    protected readonly texte: _angular_core.WritableSignal<string>;
+    /** Ce qui filtre : vide a l'ouverture par la fleche, pour montrer toute la liste. */
+    private readonly filtre;
+    /** Option active dans la liste ; le choix n'est retenu qu'a la validation. */
+    protected readonly surlignee: _angular_core.WritableSignal<string[]>;
+    protected readonly visibles: _angular_core.Signal<readonly OptionDeListe[]>;
+    private readonly liste;
+    constructor();
+    protected surSaisie(evenement: Event): void;
+    protected basculer(): void;
+    protected valider(): void;
+    protected aLaSortie(evenement: FocusEvent): void;
+    private libelleDe;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StCombobox, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StCombobox, "st-combobox", never, { "options": { "alias": "options"; "required": true; "isSignal": true; }; "filtrage": { "alias": "filtrage"; "required": false; "isSignal": true; }; }, { "recherche": "recherche"; }, never, never, true, never>;
+}
+
+/**
+ * Choix de plusieurs valeurs dans une liste, sur `@angular/aria/combobox` et
+ * `@angular/aria/listbox`.
+ *
+ * ```html
+ * <st-multiselect libelle="Comptes a inclure" [options]="comptes" [formField]="releve.comptes" />
+ * ```
+ *
+ * Le modele est la liste des VALEURS choisies, dans l'ordre des options.
+ *
+ * - Fleche bas, Entree ou Espace ouvrent la liste ; Espace coche ou decoche
+ *   l'option active sans fermer ; Echap ferme.
+ * - ⚠️ **Chaque choix reste visible et retirable** sous le champ, par un bouton
+ *   « Retirer … ». Un resume « 3 choix » dans le declencheur ne dit pas lesquels,
+ *   et obligerait a rouvrir la liste pour en retirer un.
+ * - Un choix retire rend le focus au retrait suivant, ou au champ : le focus ne
+ *   tombe jamais sur le document.
+ *
+ * ⚠️ Sous une dizaine d'options, un groupe de cases a cocher (`st-fieldset` et
+ * `st-checkbox`) est plus simple : tout est visible, rien a ouvrir.
+ */
+declare class StMultiselect extends ContratDeChamp implements FormValueControl<readonly string[]> {
+    protected readonly libelles: _angular_core.Signal<_starterlib_ui.LibellesUi>;
+    private readonly element;
+    private readonly injecteur;
+    readonly value: _angular_core.ModelSignal<readonly string[]>;
+    readonly options: _angular_core.InputSignal<readonly OptionDeListe[]>;
+    protected readonly annonce: AnnonceLocale;
+    protected readonly ouvert: _angular_core.WritableSignal<boolean>;
+    private readonly liste;
+    /** La liste d'Aria attend un tableau modifiable ; le modele, lui, est en lecture seule. */
+    protected readonly valeursDeListe: _angular_core.Signal<string[]>;
+    protected readonly choisies: _angular_core.Signal<OptionDeListe[]>;
+    protected readonly resume: _angular_core.Signal<string>;
+    constructor();
+    /** Le declencheur n'est pas un champ natif : la base ne le trouve pas par `#champ`. */
+    focus(options?: FocusOptions): void;
+    protected surChoix(valeurs: readonly string[]): void;
+    protected retirer(valeur: string, indice: number): void;
+    protected aLaSortie(evenement: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StMultiselect, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StMultiselect, "st-multiselect", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": true; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+export { StCombobox, StMultiselect, StSidenav, StSidenavToggle, StTabContent, StTabPanel, StTabs };
+export type { ActivationDOnglet, FiltrageDeListe, ModeDeNavigation, Onglet, OrientationDOnglets };

package/types/starterlib-ui-surfaces.d.ts

@@ -82,7 +82,7 @@ type TonDElementDeMenu = Extract<Ton, 'neutre' | 'danger'>;
  * actions par leur libelle, donc par leur traduction.
  */
 declare class StMenuItem {
-    readonly icone: i0.InputSignal<"boite-vide" | "cercle" | "cercle-coche" | "cercle-croix" | "cercle-info" | "chevron-bas" | "chevron-droite" | "chevron-gauche" | "chevron-haut" | "coche" | "copie" | "corbeille" | "croix" | "hors-ligne" | "lien-externe" | "menu" | "oeil" | "oeil-barre" | "plus" | "rafraichir" | "recherche" | "serveur" | "triangle-alerte" | "utilisateur" | null>;
+    readonly icone: i0.InputSignal<"boite-vide" | "calendrier" | "cercle" | "cercle-coche" | "cercle-croix" | "cercle-info" | "chevron-bas" | "chevron-droite" | "chevron-gauche" | "chevron-haut" | "coche" | "copie" | "corbeille" | "croix" | "fichier" | "hors-ligne" | "lien-externe" | "menu" | "oeil" | "oeil-barre" | "plus" | "rafraichir" | "recherche" | "serveur" | "televerser" | "triangle-alerte" | "utilisateur" | null>;
     readonly ton: i0.InputSignal<TonDElementDeMenu>;
     static ɵfac: i0.ɵɵFactoryDeclaration<StMenuItem, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<StMenuItem, "button[stMenuItem]", never, { "icone": { "alias": "icone"; "required": false; "isSignal": true; }; "ton": { "alias": "ton"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.MenuItem; inputs: { "value": "valeur"; "disabled": "desactive"; "role": "role"; }; outputs: {}; }]>;