@ktortu/aaa 0.1.0-beta.0

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

@@ -0,0 +1,110 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Provider, Signal } from '@angular/core';
+import * as _ktortu_aaa_cdk from '@ktortu/aaa/cdk';
+
+/** Contrôleur de drag-to-dismiss d'une bottom-sheet. À câbler sur le `pointerdown` de la poignée. */
+interface KtSheetDrag {
+    start(event: PointerEvent): void;
+    destroy(): void;
+}
+interface KtSheetDragOptions {
+    /** Élément translaté pendant le glissement (la feuille elle-même). Lu à chaque `start`. */
+    pane: () => HTMLElement | null;
+    /** Fermeture déclenchée quand le seuil est franchi (ex. `expanded.set(false)` / `dialogRef.close()`). */
+    onDismiss: () => void;
+    /** Classe togglée sur le pane pendant le drag (coupe la transition CSS du glissement). */
+    draggingClass: string;
+    /** Fraction de la hauteur de la feuille au-delà de laquelle on ferme (défaut 0.25). */
+    threshold?: number;
+}
+/**
+ * Drag-to-dismiss vertical (vers le BAS uniquement) d'une bottom-sheet, factorisé entre le Select
+ * (popup Popover) et le Dialog (pane CDK). Chaque appelant ne fournit que SON élément à translater
+ * et SON callback de fermeture.
+ *
+ * Geste DOUBLÉ côté appelant par Échap + bouton Fermer + tap-extérieur (WCAG 2.5.1) : ce module ne
+ * gère que le glissement. Le gating « écran compact uniquement » reste à l'appelant (signal `isCompact`
+ * de `KtViewport`) — la primitive est volontairement agnostique.
+ */
+declare function createKtSheetDrag(opts: KtSheetDragOptions): KtSheetDrag;
+
+/**
+ * Valeur d'un palier de breakpoint, CONFIGURABLE PAR APPLICATION :
+ * - un **nombre** = largeur (px) à partir de laquelle le palier commence ; la lib en dérive une
+ *   media query LARGEUR SEULE (bornes calculées par rapport au palier suivant) ;
+ * - une **chaîne** = media query complète du palier, utilisée VERBATIM (échappatoire pour un critère
+ *   non-largeur : `orientation`, `pointer`, ratio…).
+ */
+type KtBreakpointValue = number | string;
+/**
+ * Seuils responsive de la lib, surchargeables par appli via `provideKtBreakpoints`. Sémantique
+ * « plancher de palier » : chaque valeur indique où le palier COMMENCE → 3 bandes mutuellement
+ * exclusives (`mobile` < `tablet` < `desktop`).
+ */
+interface KtBreakpoints {
+    /** Plancher du mobile (typiquement 0). */
+    mobile: KtBreakpointValue;
+    /** Largeur où commence la tablette (= plafond mobile). */
+    tablet: KtBreakpointValue;
+    /** Largeur où commence le desktop (= plafond tablette). */
+    desktop: KtBreakpointValue;
+}
+/** Défauts : bascule bottom-sheet sous 600px (aligné sur l'ancien `MOBILE_QUERY`). */
+declare const KT_DEFAULT_BREAKPOINTS: KtBreakpoints;
+/** Token des seuils responsive. Défaut = `KT_DEFAULT_BREAKPOINTS` ; surchargé par `provideKtBreakpoints`. */
+declare const KT_BREAKPOINTS: InjectionToken<KtBreakpoints>;
+/**
+ * À ajouter aux `providers` de `app.config.ts`. Fusionne avec les défauts → surcharge partielle OK.
+ * @example provideKtBreakpoints({ tablet: 768, desktop: 1200 })
+ * @example provideKtBreakpoints({ tablet: '(min-width: 768px) and (orientation: landscape)' })
+ */
+declare function provideKtBreakpoints(overrides: Partial<KtBreakpoints>): Provider;
+/** Trois chaînes de media queries résolues, prêtes pour `matchMedia` / `BreakpointObserver`. */
+interface KtBreakpointMedia {
+    mobile: string;
+    tablet: string;
+    desktop: string;
+}
+/**
+ * Convertit les seuils (nombres et/ou chaînes) en 3 media queries. Un palier-chaîne est repris
+ * verbatim ; un palier-nombre devient la bande `[plancher courant .. plancher suivant[`. Si le
+ * plancher suivant est une chaîne (pas de borne numérique), la bande reste ouverte de ce côté.
+ */
+declare function resolveKtBreakpointMedia(bp: KtBreakpoints): KtBreakpointMedia;
+
+/**
+ * Expose l'état responsive courant en SIGNALS, dérivé des seuils configurés par l'appli
+ * (`KT_BREAKPOINTS` / `provideKtBreakpoints`). Fondé sur `BreakpointObserver` (`@angular/cdk/layout`,
+ * déjà dépendance) : SSR-safe (`matches: false` côté serveur → desktop par défaut) et nettoyage des
+ * listeners géré par le CDK.
+ *
+ * À injecter aussi bien dans les composants de la lib (bascule bottom-sheet) que dans le code des
+ * applis consommatrices pour leur propre layout responsive.
+ */
+declare class KtViewport {
+    private readonly observer;
+    /** Media queries résolues (largeur dérivée ou verbatim selon le token) — utile pour miroir CSS. */
+    readonly media: _ktortu_aaa_cdk.KtBreakpointMedia;
+    /** Le viewport est dans la bande mobile. */
+    readonly isMobile: Signal<boolean>;
+    /** Le viewport est dans la bande tablette. */
+    readonly isTablet: Signal<boolean>;
+    /** Le viewport est dans la bande desktop. */
+    readonly isDesktop: Signal<boolean>;
+    /** Alias de `isMobile` : palier où les composants de la lib basculent en bottom-sheet. */
+    readonly isCompact: Signal<boolean>;
+    private matches;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtViewport, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KtViewport>;
+}
+
+declare class KtIdGenerator {
+    private readonly counters;
+    private nextGlobalId;
+    generateId(prefix?: string): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtIdGenerator, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KtIdGenerator>;
+}
+
+export { KT_BREAKPOINTS, KT_DEFAULT_BREAKPOINTS, KtIdGenerator, KtViewport, createKtSheetDrag, provideKtBreakpoints, resolveKtBreakpointMedia };
+export type { KtBreakpointMedia, KtBreakpointValue, KtBreakpoints, KtSheetDrag, KtSheetDragOptions };

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

@@ -0,0 +1,286 @@
+import * as i0 from '@angular/core';
+import { OnInit, OnDestroy, Provider } from '@angular/core';
+import { DialogConfig, DialogRef, CdkDialogContainer } from '@angular/cdk/dialog';
+import { ComponentType } from '@angular/cdk/portal';
+
+/**
+ * À poser sur le titre VISIBLE (idéalement un `<h2>`) du contenu d'un CDK Dialog.
+ * Câble `aria-labelledby` du conteneur de dialogue.
+ *
+ * Pourquoi écrire l'attribut directement (Renderer2) plutôt que seulement `_addAriaLabelledBy` :
+ * sous change detection ZONELESS (cas par défaut moderne), le `markForCheck()` interne du
+ * conteneur ne rafraîchit pas ses host bindings à l'ouverture, donc l'attribut n'apparaîtrait
+ * jamais. On écrit donc l'attribut nous-mêmes (fiable, indépendant de la CD) ET on alimente la
+ * file CDK pour rester cohérent si un cycle de CD survient ensuite.
+ *
+ * @example
+ * ```html
+ * <h2 ktDialogTitle>Renommer le fichier</h2>
+ * ```
+ */
+declare class KtDialogTitle {
+    private readonly dialogRef;
+    private readonly host;
+    private readonly renderer;
+    private readonly idGen;
+    /** Id de l'hôte câblé en `aria-labelledby` : préserve un id fourni par le consommateur, sinon en génère un. */
+    readonly id: string;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogTitle, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogTitle, "[ktDialogTitle]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * À poser sur le paragraphe descriptif COURT du dialog : câble `aria-describedby` du conteneur
+ * (texte lu par le lecteur d'écran juste après le titre, à l'ouverture).
+ *
+ * ⚠️ Ne JAMAIS appliquer sur un formulaire ou un long contenu : `aria-describedby` concatène
+ * tout le texte du nœud et serait lu d'un bloc à l'ouverture. Réserver à une phrase de contexte.
+ *
+ * Écriture directe de l'attribut (Renderer2) pour la même raison que `ktDialogTitle` :
+ * fiabilité sous change detection zoneless. La config est tenue à jour pour cohérence CDK.
+ *
+ * @example
+ * ```html
+ * <p ktDialogDescription>Cette action est définitive.</p>
+ * ```
+ */
+declare class KtDialogDescription implements OnInit, OnDestroy {
+    private readonly dialogRef;
+    private readonly host;
+    private readonly renderer;
+    private readonly idGen;
+    /** Id de l'hôte câblé en `aria-describedby` : préserve un id fourni par le consommateur, sinon en génère un. */
+    readonly id: string;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogDescription, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogDescription, "[ktDialogDescription]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Ferme le CDK Dialog au clic, avec un résultat optionnel renvoyé à l'ouvreur via
+ * `DialogRef.close(result)`. Se compose avec `[ktButton]` sur le même `<button>`.
+ *
+ * Réservé au DISMISS simple (Annuler / Fermer). Pour valider un formulaire, injectez
+ * `DialogRef` dans votre composant et appelez `close(valeur)` après validation.
+ *
+ * @example
+ * ```html
+ * <button ktButton ktDialogClose>Annuler</button>
+ * <button ktButton [ktDialogClose]="'confirm'">Confirmer</button>
+ * ```
+ */
+declare class KtDialogClose {
+    private readonly dialogRef;
+    private readonly host;
+    /**
+     * Valeur renvoyée à l'ouvreur via `DialogRef.close(result)`. Liée par l'alias `ktDialogClose`
+     * (= nom du sélecteur), d'où l'usage `[ktDialogClose]="'confirm'"`. @default undefined
+     */
+    readonly dialogResult: i0.InputSignal<unknown>;
+    protected readonly buttonType: string | null;
+    constructor();
+    protected close(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogClose, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogClose, "[ktDialogClose]", never, { "dialogResult": { "alias": "ktDialogClose"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * En-tête RICHE et OPTIONNEL du dialog : rangée flex pour composer une icône, le titre et/ou un
+ * bouton de fermeture. Marqueur structurel sans logique — la mise en forme (flex, padding de
+ * région, reset du padding du [ktDialogTitle] qu'il enveloppe) vit dans `dialog.css`.
+ *
+ * Sépare le LAYOUT (cette région) de l'ÉTIQUETTE ACCESSIBLE ([ktDialogTitle], qui garde
+ * aria-labelledby). En usage simple — titre nu sans header — [ktDialogTitle] conserve son propre
+ * padding : ce header n'est à utiliser que pour les en-têtes composés (icône, close top-right…).
+ *
+ * @example
+ * ```html
+ * <header ktDialogHeader>
+ *   <h2 ktDialogTitle>Titre</h2>
+ *   <button ktButton ktDialogClose aria-label="Fermer">✕</button>
+ * </header>
+ * ```
+ */
+declare class KtDialogHeader {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogHeader, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogHeader, "[ktDialogHeader]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Zone de contenu du dialog. Marqueur structurel sans logique : la mise en forme
+ * (rythme vertical) vit dans `dialog.css` via le sélecteur `[ktDialogContent]`.
+ *
+ * @example
+ * ```html
+ * <div ktDialogContent>…</div>
+ * ```
+ */
+declare class KtDialogContent {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogContent, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogContent, "[ktDialogContent]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Barre d'actions du dialog (rangée de boutons). Marqueur structurel sans logique :
+ * la mise en forme (flex, gap, sticky bas pour le Reflow AAA) vit dans `dialog.css`
+ * via le sélecteur `[ktDialogActions]`.
+ *
+ * @example
+ * ```html
+ * <footer ktDialogActions>
+ *   <button ktButton ktDialogClose>Annuler</button>
+ *   <button ktButton [ktDialogClose]="'ok'">Valider</button>
+ * </footer>
+ * ```
+ */
+declare class KtDialogActions {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogActions, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogActions, "[ktDialogActions]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marque l'élément à focaliser à l'ouverture. À coupler avec la config CDK
+ * `autoFocus: '[ktDialogFocusInitial]'` (incluse dans `provideKtDialogDefaults`).
+ * Permet d'éviter que le focus initial tombe sur une action destructrice.
+ *
+ * @example
+ * ```html
+ * <input ktDialogFocusInitial type="text" />
+ * ```
+ */
+declare class KtDialogFocusInitial {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogFocusInitial, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogFocusInitial, "[ktDialogFocusInitial]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Poignée de préhension d'un dialog en mode `sheet` (bottom-sheet) : drag-to-dismiss vers le bas,
+ * FACTORISÉ avec le Select via `createKtSheetDrag` (@ktortu/aaa). Geste DOUBLÉ par Échap + bouton
+ * Fermer + clic sur le scrim (WCAG 2.5.1) — décoratif (`aria-hidden`).
+ *
+ * À poser sur la barre de préhension, premier enfant du contenu d'un dialog ouvert avec une
+ * présentation `sheet` / `centered-sheet`. Le drag n'est actif que si le dialog est EFFECTIVEMENT
+ * en mode sheet (la pane porte `kt-dialog--sheet`) — pas de dépendance au viewport : un `sheet`
+ * toujours-bottom-sheet se drague aussi à la souris.
+ *
+ * @example
+ * ```html
+ * <div ktDialogContent>
+ *   <div ktDialogSheetHandle></div>
+ *   …
+ * </div>
+ * ```
+ */
+declare class KtDialogSheetHandle {
+    private readonly dialogRef;
+    private readonly host;
+    private readonly destroyRef;
+    private readonly drag;
+    constructor();
+    protected onStart(event: PointerEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogSheetHandle, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KtDialogSheetHandle, "[ktDialogSheetHandle]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Valeurs par défaut orientées AAA pour `@angular/cdk/dialog`.
+ * - `ariaModal: true` : explicite (le CDK le laisse OFF par défaut).
+ * - `restoreFocus: true` : rend le focus au déclencheur à la fermeture.
+ * - `panelClass` / `backdropClass` : crochets de style consommés par `dialog.css`.
+ *
+ * Pour focaliser un élément précis à l'ouverture (ex. éviter un bouton destructeur),
+ * passez `autoFocus: '[ktDialogFocusInitial]'` dans la config d'ouverture et posez la
+ * directive `ktDialogFocusInitial` sur la cible.
+ */
+declare const KT_DIALOG_AAA_DEFAULTS: DialogConfig;
+/**
+ * Enregistre les valeurs par défaut AAA du dialog au niveau application.
+ * À ajouter aux `providers` de `app.config.ts`. `overrides` permet d'ajuster sans
+ * tout réécrire (ex. `provideKtDialogDefaults({ maxWidth: '40rem' })`).
+ */
+declare function provideKtDialogDefaults(overrides?: Partial<DialogConfig>): Provider;
+/**
+ * Présentation du dialog, CHOISIE EXPLICITEMENT PAR LE DÉVELOPPEUR à l'ouverture (option
+ * `presentation` de `injectKtDialogOpener`). Aucune bascule CSS automatique : le dev décide.
+ * - `centered`            : toujours centré (ex. confirmation) — DÉFAUT ;
+ * - `fullscreen`          : toujours plein écran (desktop compris) ;
+ * - `sheet`               : toujours bottom-sheet (desktop compris) ;
+ * - `centered-fullscreen` : centré sur desktop, plein écran sur téléphone compact ;
+ * - `centered-sheet`      : centré sur desktop, bottom-sheet sur téléphone compact.
+ * Les variantes `centered-*` sont résolues EN JS à l'ouverture (signal `KtViewport.isCompact()`), pas par le CSS —
+ * la classe CSS finale est donc toujours une présentation CONCRÈTE (centered/fullscreen/sheet).
+ */
+type KtDialogPresentation = 'centered' | 'fullscreen' | 'sheet' | 'centered-fullscreen' | 'centered-sheet';
+/**
+ * Résout une `KtDialogPresentation` (responsive comprise) en panelClass concret. Pour les variantes
+ * `centered-*`, l'appelant fournit `compact` (= `KtViewport.isCompact()`, largeur seule) — centré
+ * sur desktop, plein écran / sheet sur écran compact. Fonction pure (testable sans DOM).
+ * Appelée par `injectKtDialogOpener` à chaque ouverture ; exportée pour un usage direct éventuel.
+ */
+declare function resolveKtDialogPanelClass(presentation?: KtDialogPresentation, compact?: boolean): string[];
+
+/**
+ * Sucre typé pour récupérer les données injectées dans un composant de dialogue (`DIALOG_DATA`).
+ * À appeler en contexte d'injection (ex. initialiseur de champ).
+ *
+ * @example
+ * ```ts
+ * interface RenameData { currentName: string; }
+ *
+ * @Component({  …  })
+ * export class RenameDialog {
+ *   protected readonly data = injectKtDialogData<RenameData>();
+ *   // this.data.currentName  →  string
+ * }
+ * ```
+ */
+declare function injectKtDialogData<T>(): T;
+/** Config d'ouverture sans le champ `data` (fourni séparément, typé), enrichie de `presentation`. */
+type OpenerConfig<D, R, C> = Omit<DialogConfig<D, DialogRef<R, C>>, 'data'> & {
+    /** Présentation du dialog (cf. `KtDialogPresentation`) — choisie par le dev. Résolue à CHAQUE
+        ouverture : les variantes responsive lisent le signal d'écran compact. Défaut : `'centered'`.
+        Combinée à un éventuel `panelClass` additionnel. */
+    presentation?: KtDialogPresentation;
+};
+/**
+ * Crée un ouvreur de dialog **typé et centralisé**, en contexte d'injection.
+ * Le contrat (composant + type de `data` + type de résultat + config par défaut) est défini
+ * UNE fois ; l'ouvreur renvoyé est une closure appelable ensuite n'importe où dans la classe
+ * (handlers compris), 100 % typée, sans nouvel `inject`.
+ *
+ * Conserve le `ViewContainerRef` du contexte appelant (le dialog hérite donc de l'arbre logique
+ * d'injection), reste testable (TestBed fournit `Dialog`) et sans état global (SSR-safe).
+ *
+ * @example
+ * // co-localisé avec le composant
+ * export const injectRenameDialog = () =>
+ *   injectKtDialogOpener<RenameDialog, RenameData, string>(RenameDialog, { autoFocus: '[ktDialogFocusInitial]' });
+ *
+ * // dans un composant/service consommateur
+ * private readonly openRename = injectRenameDialog();
+ * rename() { this.openRename({ currentName: 'X' }).closed.subscribe(n => {  n: string | undefined  }); }
+ */
+declare function injectKtDialogOpener<C, R = unknown>(component: ComponentType<C>, baseConfig?: OpenerConfig<void, R, C>): () => DialogRef<R, C>;
+declare function injectKtDialogOpener<C, D, R = unknown>(component: ComponentType<C>, baseConfig?: OpenerConfig<D, R, C>): (data: D, config?: OpenerConfig<D, R, C>) => DialogRef<R, C>;
+
+declare class KtDialogContainer extends CdkDialogContainer implements OnInit {
+    private readonly dialogRef;
+    private readonly elementRef;
+    private readonly host;
+    private readonly platformId;
+    protected readonly isClosing: i0.WritableSignal<boolean>;
+    constructor();
+    ngOnInit(): void;
+    protected isSheet(): boolean;
+    private animateAndClose;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KtDialogContainer, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KtDialogContainer, "kt-dialog-container", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Import ergonomique de toute la famille dialog en une fois :
+ * `imports: [KT_DIALOG]` au lieu d'énumérer chaque directive structurelle.
+ */
+declare const KT_DIALOG: readonly [typeof KtDialogHeader, typeof KtDialogTitle, typeof KtDialogDescription, typeof KtDialogContent, typeof KtDialogActions, typeof KtDialogClose, typeof KtDialogFocusInitial, typeof KtDialogSheetHandle];
+
+export { KT_DIALOG, KT_DIALOG_AAA_DEFAULTS, KtDialogActions, KtDialogClose, KtDialogContainer, KtDialogContent, KtDialogDescription, KtDialogFocusInitial, KtDialogHeader, KtDialogSheetHandle, KtDialogTitle, injectKtDialogData, injectKtDialogOpener, provideKtDialogDefaults, resolveKtDialogPanelClass };
+export type { KtDialogPresentation };