@ktortu/aaa 0.9.0 → 0.9.2

package/types/ktortu-aaa-i18n.d.ts

@@ -1,5 +1,6 @@
 import { EnvironmentProviders } from '@angular/core';
 import { KtFieldConfig, KtSelectConfigOptions, KtChipsConfig } from '@ktortu/aaa/forms';
+import { KtSnackbarConfig } from '@ktortu/aaa/snackbar';
 import { KtTabsConfig } from '@ktortu/aaa/tabs';
 
 /**
@@ -18,6 +19,8 @@ interface KtTranslations {
     select?: Partial<KtSelectConfigOptions>;
     /** Libellés des listes de chips → {@link KT_CHIPS_CONFIG}. */
     chips?: Partial<KtChipsConfig>;
+    /** Libellés de la snackbar (`closeLabel`) → {@link KT_SNACKBAR_CONFIG}. */
+    snackbar?: Partial<KtSnackbarConfig>;
     /** Libellés de la pagination des onglets → {@link KT_TABS_CONFIG}. */
     tabs?: Partial<KtTabsConfig>;
 }

package/types/ktortu-aaa-progress-bar.d.ts

@@ -0,0 +1,27 @@
+import * as _angular_core from '@angular/core';
+import { AfterViewInit } from '@angular/core';
+
+declare class KtProgressBar implements AfterViewInit {
+    private readonly idGen;
+    private readonly elementRef;
+    protected readonly labelId: string;
+    private readonly hasProjectedContent;
+    /** Mode de fonctionnement de la barre de progression. @default 'indeterminate' */
+    readonly mode: _angular_core.InputSignal<"determinate" | "indeterminate">;
+    /** Valeur de la progression (entre 0 et 100). Ignorée en mode 'indeterminate'. @default 0 */
+    readonly value: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Label textuel optionnel passé par attribut. */
+    readonly label: _angular_core.InputSignal<string | undefined>;
+    /** Détermine si le label textuel doit être visible à l'écran. @default true */
+    readonly labelVisible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Permet de figer l'animation indéterminée (utile pour les tests). @default false */
+    readonly reducedMotion: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Indique si le composant dispose d'un label défini (soit via input, soit par projection). */
+    protected readonly hasLabel: _angular_core.Signal<boolean>;
+    protected readonly transformStyle: _angular_core.Signal<string | null>;
+    ngAfterViewInit(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KtProgressBar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KtProgressBar, "kt-progress-bar", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelVisible": { "alias": "labelVisible"; "required": false; "isSignal": true; }; "reducedMotion": { "alias": "reducedMotion"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+export { KtProgressBar };

package/types/ktortu-aaa-snackbar.d.ts

@@ -0,0 +1,218 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Provider, OnDestroy } from '@angular/core';
+import { Observable } from 'rxjs';
+
+/** Politesse de l'annonce au lecteur d'écran (relayée à `LiveAnnouncer`). */
+type KtSnackbarPoliteness = 'polite' | 'assertive';
+/** Bord d'ancrage de la snackbar dans le viewport. */
+type KtSnackbarPosition = 'top' | 'bottom';
+/**
+ * Régime temporel de la snackbar :
+ * - `'auto'` : disparition automatique après `duration`, **mise en pause au survol et au focus**
+ *   clavier (WCAG 1.4.13 / 2.2.1). Conforme **AA**. C'est le défaut.
+ * - `'manual'` : **aucune** minuterie, la snackbar reste jusqu'à fermeture explicite
+ *   (bouton de fermeture ou `ref.dismiss()`). Conforme **2.2.3 (AAA)** au sens strict.
+ *
+ * Conformément aux recommandations d'accessibilité (Roselli/Soueidan), la snackbar ne porte **pas
+ * d'action interactive** (ex. « Annuler ») : une action auto-disparaissante n'est pas atteignable et
+ * une live region n'expose pas ses boutons. Pour un undo, préférez un mécanisme atteignable côté app
+ * (Ctrl+Z, bannière persistante).
+ */
+type KtSnackbarTiming = 'auto' | 'manual';
+/**
+ * Variante sémantique de la snackbar. Pilote uniquement l'**apparence** (couleur d'accent + icône),
+ * via l'attribut `data-variant` et les tokens CSS `--snackbar-*` — donc entièrement gérée par le
+ * thème, sans logique TypeScript. Découplée de la `politeness` (une « erreur » n'est pas forcément
+ * une urgence assertive). La couleur n'est jamais le seul indice : chaque variante porte une **icône**
+ * de forme distincte (WCAG 1.4.1).
+ * - `'neutral'` : pastille neutre, sans icône (défaut) ;
+ * - `'info' | 'success' | 'warning' | 'error'` : accent + icône dédiés.
+ */
+type KtSnackbarVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error';
+/**
+ * Défauts de la snackbar, injectables via `provideKtSnackbar` / `KT_SNACKBAR_CONFIG`.
+ * Tous les champs sont surchargeables **par appel** via les options de `KtSnackbar.open()`.
+ *
+ * Résolution en cascade (convention de la lib) : `option d'open ?? KT_SNACKBAR_CONFIG ?? défaut`.
+ */
+interface KtSnackbarConfig {
+    /**
+     * Durée d'affichage en régime `'auto'`. Soit un **nombre fixe** (ms), soit le sentinel
+     * **`'reading-time'`** (DÉFAUT) qui **calcule** la durée d'après la longueur du message :
+     * `clamp(longueur × readingTimePerChar, readingTimeMin, readingTimeMax)`. Passer un nombre à
+     * `open()` force donc une durée fixe pour cet appel.
+     *
+     * ⚠️ Gardez le message **court** : une snackbar est un message transitoire (pas un paragraphe).
+     * Un message long fait grimper la durée jusqu'au plafond `readingTimeMax`.
+     * @default 'reading-time'
+     */
+    duration: number | 'reading-time';
+    /** Plancher (ms) de la durée calculée (`'reading-time'`) — laisse le temps de lire un message court. @default 4000 */
+    readingTimeMin: number;
+    /** Plafond (ms) de la durée calculée (`'reading-time'`) — borne un message long. @default 10000 */
+    readingTimeMax: number;
+    /** Coefficient de lecture : millisecondes ajoutées par caractère du message. @default 60 (~200 mots/min) */
+    readingTimePerChar: number;
+    /** Régime temporel (cf. {@link KtSnackbarTiming}). @default 'auto' (AA + pause) */
+    timing: KtSnackbarTiming;
+    /** Bord d'ancrage dans le viewport. @default 'bottom' */
+    position: KtSnackbarPosition;
+    /** Politesse de l'annonce lecteur d'écran. @default 'polite' */
+    politeness: KtSnackbarPoliteness;
+    /** Variante sémantique (apparence seule, cf. {@link KtSnackbarVariant}). @default 'neutral' */
+    variant: KtSnackbarVariant;
+    /** Affiche un bouton de fermeture (cible 44px, AAA). @default true */
+    closable: boolean;
+    /** Nom accessible du bouton de fermeture. @default 'Close' (FR fourni en lot L3) */
+    closeLabel: string;
+    /**
+     * Taille maximale de la file FIFO (snackbar affichée + en attente). Au-delà, les **plus anciennes
+     * en attente** sont retirées silencieusement. Une seule snackbar est visible à la fois. @default 3
+     */
+    max: number;
+}
+/** Défauts AAA-orientés de la snackbar (anglais neutre). */
+declare const KT_SNACKBAR_DEFAULTS: KtSnackbarConfig;
+declare const KT_SNACKBAR_CONFIG: InjectionToken<Partial<KtSnackbarConfig>>;
+/**
+ * Options ponctuelles d'ouverture d'une snackbar : un sous-ensemble (toutes facultatives) de la
+ * config, prioritaire sur `KT_SNACKBAR_CONFIG` et sur les défauts.
+ */
+type KtSnackbarOptions = Partial<KtSnackbarConfig>;
+/**
+ * Fournit des défauts de snackbar pour un sous-arbre ou l'application entière.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts — bascule TOUTE l'app en AAA strict (aucune disparition automatique)
+ * providers: [provideKtSnackbar({ timing: 'manual' })]
+ * ```
+ * @example
+ * ```ts
+ * providers: [provideKtSnackbar({ duration: 8000, position: 'top' })]
+ * ```
+ */
+declare function provideKtSnackbar(config: Partial<KtSnackbarConfig>): Provider;
+
+/**
+ * Raison de fermeture d'une snackbar, transmise par {@link KtSnackbarRef.afterDismissed}.
+ * - `'timeout'` : la minuterie (régime `'auto'`) est arrivée à échéance ;
+ * - `'dismiss'` : fermeture explicite (bouton de fermeture, `Échap`, ou `ref.dismiss()`) ;
+ * - `'replaced'` : la snackbar a été retirée de la file sans être affichée (file pleine — cf. `max`).
+ */
+type KtSnackbarDismissReason = 'timeout' | 'dismiss' | 'replaced';
+/**
+ * Référence d'une snackbar ouverte, renvoyée par `KtSnackbar.open()`. Permet de fermer la
+ * snackbar par programmation et d'observer sa fermeture.
+ *
+ * Le débutant peut l'ignorer (`snackbar.open('…')`) ; le code avancé s'en sert pour piloter la
+ * fermeture et réagir à la raison de fin.
+ *
+ * @example
+ * ```ts
+ * const ref = snackbar.open('Brouillon enregistré');
+ * ref.afterDismissed().subscribe((reason) => console.log(reason)); // 'timeout' | 'dismiss' | 'replaced'
+ * // plus tard : ref.dismiss();
+ * ```
+ */
+declare class KtSnackbarRef {
+    private readonly onDismiss;
+    private readonly _afterDismissed;
+    private settled;
+    /**
+     * @param onDismiss Rappel exécuté une fois à la fermeture (animation de sortie + démontage de
+     *   l'overlay + avance de la file), fourni par le service.
+     * @internal Construit par `KtSnackbar` — n'instanciez pas `KtSnackbarRef` directement.
+     */
+    constructor(onDismiss: (reason: KtSnackbarDismissReason) => void);
+    /**
+     * Ferme la snackbar (idempotent). Déclenche la sortie/démontage puis émet la raison sur
+     * `afterDismissed()`.
+     * @param reason Raison de fermeture. @default 'dismiss'
+     */
+    dismiss(reason?: KtSnackbarDismissReason): void;
+    /** Émet une fois (puis complète) à la fermeture, avec la {@link KtSnackbarDismissReason}. */
+    afterDismissed(): Observable<KtSnackbarDismissReason>;
+}
+
+/**
+ * Service d'ouverture des snackbars `@ktortu/aaa` — feedback **non bloquant** qui confirme une
+ * action ou signale un événement transitoire sans interrompre la tâche (n'utilisez PAS de snackbar
+ * pour une information critique à acquitter : préférez le dialog).
+ *
+ * Architecture a11y :
+ * - **CDK Overlay** pour le panneau visuel, **CDK LiveAnnouncer** pour l'annonce — **un seul canal**
+ *   d'annonce (le panneau n'est pas une live region) ;
+ * - **le focus n'est jamais déplacé** vers la snackbar (RGAA « message de statut » / WCAG 4.1.3) ;
+ * - disparition automatique **en pause au survol et au focus** (régime `'auto'`, défaut AA), ou
+ *   persistante (`timing: 'manual'`, AAA) ;
+ * - **file FIFO** : une seule snackbar visible, les suivantes patientent (live region non saturée).
+ *   La file est bornée par `max` (défaut 3) ; les messages **identiques** sont fusionnés (coalescing) ;
+ * - **Échap** ferme la snackbar affichée (la plus récente).
+ *
+ * Requiert côté hôte les styles `@angular/cdk/overlay-prebuilt.css` **et**
+ * `@angular/cdk/a11y-prebuilt.css` (ce dernier masque l'élément du LiveAnnouncer), en plus de
+ * `@ktortu/aaa/snackbar.css`.
+ *
+ * > [!IMPORTANT]
+ * > **Prérequis d'intégration obligatoire :**
+ * > Ce service ne fonctionnera pas correctement sans l'importation de ces deux fichiers CSS de l'overlay CDK et d'accessibilité dans votre feuille de styles globale ou votre build.
+ *
+ * @example
+ * ```ts
+ * private readonly snackbar = inject(KtSnackbar);
+ * this.snackbar.open('Brouillon enregistré');                       // disparaît, annonce polie
+ * this.snackbar.open('Fichier supprimé', { variant: 'success' });   // variante (couleur + icône)
+ * this.snackbar.open('Hors ligne', { timing: 'manual' });           // reste jusqu'à fermeture (AAA)
+ * ```
+ */
+declare class KtSnackbar implements OnDestroy {
+    private readonly overlay;
+    private readonly injector;
+    private readonly liveAnnouncer;
+    private readonly config;
+    private readonly platformId;
+    private readonly doc;
+    /** File FIFO : `queue[0]` est la snackbar affichée dès qu'elle est attachée. */
+    private readonly queue;
+    private active;
+    private escapeRegistered;
+    /**
+     * Ouvre une snackbar affichant `message`. Les `options` priment sur `KT_SNACKBAR_CONFIG`, qui
+     * prime sur les défauts. Renvoie une {@link KtSnackbarRef} (ignorable dans le cas simple).
+     *
+     * Une seule snackbar est visible : si une autre est affichée, celle-ci patiente en file (FIFO).
+     * Un `message` identique à une snackbar déjà affichée ou en attente est **fusionné** : on renvoie
+     * alors la référence existante sans rien ré-empiler.
+     *
+     * > [!IMPORTANT]
+     * > Assurez-vous d'avoir importé `@angular/cdk/overlay-prebuilt.css` et `@angular/cdk/a11y-prebuilt.css` dans votre application hôte.
+     *
+     * @param message Texte affiché et annoncé au lecteur d'écran.
+     * @param options Surcharges ponctuelles (durée, régime, position, politesse, variante, fermeture).
+     * @returns La référence de la snackbar (existante en cas de fusion).
+     */
+    open(message: string, options?: KtSnackbarOptions): KtSnackbarRef;
+    ngOnDestroy(): void;
+    /** Borne la file (affichée + en attente) : retire les plus ANCIENNES en attente au-delà de `max`. */
+    private enforceMax;
+    /** Affiche la tête de file si rien n'est actuellement visible. */
+    private showHead;
+    /** Retire l'élément de la file ; s'il est affiché, joue la sortie puis démonte et avance la file. */
+    private handleDismiss;
+    private readonly onDocumentKeydown;
+    private registerEscape;
+    private unregisterEscape;
+    /**
+     * Durée effective (ms) en régime `'auto'`. Un nombre est pris tel quel (durée fixe) ; le sentinel
+     * `'reading-time'` calcule `clamp(longueur × perChar, min, max)`.
+     */
+    private computeDuration;
+    /** Résolution en cascade `option ?? KT_SNACKBAR_CONFIG ?? défaut`, champ par champ. */
+    private resolve;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtSnackbar, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KtSnackbar>;
+}
+
+export { KT_SNACKBAR_CONFIG, KT_SNACKBAR_DEFAULTS, KtSnackbar, KtSnackbarRef, provideKtSnackbar };
+export type { KtSnackbarConfig, KtSnackbarDismissReason, KtSnackbarOptions, KtSnackbarPoliteness, KtSnackbarPosition, KtSnackbarTiming, KtSnackbarVariant };

package/types/ktortu-aaa-tooltip.d.ts

@@ -39,7 +39,6 @@ declare class KtTooltip implements OnDestroy {
     private readonly host;
     private readonly renderer;
     private readonly vcr;
-    private readonly ngZone;
     private readonly platformId;
     /** Contenu de l'infobulle : texte simple (injecté en `textContent`) ou `TemplateRef` non interactif. */
     readonly ktTooltip: _angular_core.InputSignal<string | TemplateRef<unknown>>;

package/types/ktortu-aaa.d.ts

@@ -5,5 +5,7 @@ export * from '@ktortu/aaa/dialog';
 export * from '@ktortu/aaa/forms';
 export * from '@ktortu/aaa/i18n';
 export * from '@ktortu/aaa/menu';
+export * from '@ktortu/aaa/snackbar';
 export * from '@ktortu/aaa/tabs';
 export * from '@ktortu/aaa/tooltip';
+export * from '@ktortu/aaa/progress-bar';