@ktortu/aaa 0.9.0 → 0.9.1

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

@@ -0,0 +1,275 @@
+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).
+ *
+ * @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.
+     *
+     * @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>;
+}
+
+/**
+ * Données résolues passées au conteneur visuel à l'ouverture (injectées via {@link KT_SNACKBAR_CONTEXT}).
+ * Produites par `KtSnackbar` après résolution `option ?? config ?? défaut`.
+ */
+interface KtSnackbarContext {
+    /** Message affiché et annoncé. */
+    readonly message: string;
+    /** Variante sémantique (apparence : accent + icône). */
+    readonly variant: KtSnackbarVariant;
+    /** Affiche le bouton de fermeture. */
+    readonly closable: boolean;
+    /** Nom accessible du bouton de fermeture. */
+    readonly closeLabel: string;
+    /** Régime temporel (la minuterie n'existe qu'en `'auto'`). */
+    readonly timing: KtSnackbarTiming;
+    /** Durée (ms) avant disparition automatique en régime `'auto'`. */
+    readonly duration: number;
+}
+declare const KT_SNACKBAR_CONTEXT: InjectionToken<KtSnackbarContext>;
+/**
+ * Conteneur visuel d'une snackbar. **Volontairement pas une live region** (aucun `role`/`aria-live`
+ * sur l'hôte) : l'annonce passe par un canal UNIQUE, le `LiveAnnouncer` du service. On évite ainsi
+ * la double-annonce et l'écrasement de politesse observés sur d'autres libs.
+ *
+ * En régime `'auto'`, la minuterie de disparition se met **en pause au survol et au focus** clavier
+ * (WCAG 1.4.13 / 2.2.1) et reprend quand ni le pointeur ni le focus ne sont sur la snackbar.
+ * L'icône de variante est **décorative** (`aria-hidden`) : la forme distincte sert d'indice non
+ * coloré (WCAG 1.4.1), le sens reste porté par le texte.
+ *
+ * @internal Monté par `KtSnackbar` via un `ComponentPortal`.
+ */
+declare class KtSnackbarContainer {
+    protected readonly context: KtSnackbarContext;
+    private readonly ref;
+    private readonly platformId;
+    private readonly host;
+    /** Vrai pendant l'animation de sortie (déclenche la classe `kt-snackbar--leaving`). */
+    protected readonly leaving: i0.WritableSignal<boolean>;
+    private timer;
+    private remaining;
+    private deadline;
+    private hovered;
+    private focused;
+    constructor();
+    protected close(): void;
+    /**
+     * Joue l'animation de sortie puis invoque `done` (démontage de l'overlay côté service). Appelé par
+     * le service à la fermeture. Sans animation (durée nulle, `prefers-reduced-motion`, ou SSR), `done`
+     * est invoqué immédiatement. Filet de sécurité par `setTimeout` si `transitionend` ne se déclenche pas.
+     */
+    playExit(done: () => void): void;
+    protected onPointerEnter(): void;
+    protected onPointerLeave(): void;
+    protected onFocusEnter(): void;
+    protected onFocusLeave(): void;
+    private maybeResume;
+    private startTimer;
+    private pauseTimer;
+    private clearTimer;
+    /** Durée (ms) de la transition de sortie, lue sur l'hôte (0 si aucune — ex. reduced-motion). */
+    private exitDurationMs;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtSnackbarContainer, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KtSnackbarContainer, "kt-snackbar-container", never, {}, {}, never, never, true, never>;
+}
+
+export { KT_SNACKBAR_CONFIG, KT_SNACKBAR_CONTEXT, KT_SNACKBAR_DEFAULTS, KtSnackbar, KtSnackbarContainer, KtSnackbarRef, provideKtSnackbar };
+export type { KtSnackbarConfig, KtSnackbarContext, KtSnackbarDismissReason, KtSnackbarOptions, KtSnackbarPoliteness, KtSnackbarPosition, KtSnackbarTiming, KtSnackbarVariant };

package/types/ktortu-aaa.d.ts

@@ -5,5 +5,6 @@ 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';