@ktortu/aaa 0.9.0 → 0.9.1

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

@@ -250,19 +250,13 @@ type KtDialogPresentation = 'centered' | 'fullscreen' | 'sheet' | 'centered-full
 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; }
+ * ⚠️ API BAS-NIVEAU — n'utilisez PAS ceci par défaut. Pour implémenter un dialog, passez par
+ * {@link defineKtDialog} et son `injectData()` (qui lie le type des données à l'ouvreur).
  *
- * @Component({  …  })
- * export class RenameDialog {
- *   protected readonly data = injectKtDialogData<RenameData>();
- *   // this.data.currentName  →  string
- * }
- * ```
+ * Sucre typé pour récupérer les données injectées dans un composant de dialogue (`DIALOG_DATA`).
+ * Le type `T` est affirmé ICI indépendamment de l'ouvreur : rien ne garantit qu'il corresponde au
+ * type passé à `injectKtDialogOpener` → risque de divergence silencieuse. À réserver à un cas où
+ * `defineKtDialog` ne convient pas.
  */
 declare function injectKtDialogData<T>(): T;
 /** Config d'ouverture sans le champ `data` (fourni séparément, typé), enrichie de `presentation`. */
@@ -273,29 +267,97 @@ type KtDialogOpenerConfig<D, R, C> = Omit<DialogConfig<D, DialogRef<R, C>>, 'dat
     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`.
+ * ⚠️ API BAS-NIVEAU — n'utilisez PAS ceci par défaut. Pour implémenter un dialog, passez par
+ * {@link defineKtDialog} puis son `injectOpener(...)` : il fixe données + résultat une seule fois et
+ * les partage avec `injectData()`/`injectRef()`. N'appelez `injectKtDialogOpener` directement que
+ * dans un cas avancé où le contrat groupé de `defineKtDialog` ne convient pas.
+ *
+ * Crée un ouvreur de dialog typé en contexte d'injection : le contrat (composant + type de `data` +
+ * type de résultat + config par défaut) est figé via les génériques `<Composant, Data, Résultat>`
+ * (qu'il faut répéter — d'où la préférence pour `defineKtDialog`). L'ouvreur renvoyé est une closure
+ * appelable n'importe où dans la classe, 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  }); }
- *
  * @param component Composant à monter dans le dialog.
  * @param baseConfig Config d'ouverture par défaut (sans `data`), enrichie de `presentation` ; fusionnée à chaque ouverture.
  * @returns Une closure d'ouverture typée : `() => DialogRef` (sans data) ou `(data, config?) => DialogRef` (avec data).
+ * @see {@link defineKtDialog} — la façon recommandée d'obtenir cet ouvreur.
  */
 declare function injectKtDialogOpener<C, R = unknown>(component: ComponentType<C>, baseConfig?: KtDialogOpenerConfig<void, R, C>): () => DialogRef<R, C>;
 declare function injectKtDialogOpener<C, D, R = unknown>(component: ComponentType<C>, baseConfig?: KtDialogOpenerConfig<D, R, C>): (data: D, config?: KtDialogOpenerConfig<D, R, C>) => DialogRef<R, C>;
+/**
+ * Contrat de dialog typé renvoyé par `defineKtDialog` : les trois accès (données, référence,
+ * ouvreur) dérivent des MÊMES génériques `D`/`R`, déclarés une seule fois — impossible donc que
+ * le type des données ou du résultat diverge entre le composant et l'ouvreur.
+ *
+ * @template D Type des données injectées (`void` si aucune).
+ * @template R Type du résultat renvoyé à la fermeture.
+ */
+interface KtDialogContract<D, R> {
+    /** Données injectées (à appeler en contexte d'injection DANS le composant de dialog). */
+    injectData(): D;
+    /** Référence typée du dialog : `close()` n'accepte QUE le résultat `R` (sûreté de fermeture). */
+    injectRef(): DialogRef<R>;
+    /** Ouvreur typé CO-LOCALISÉ pour ce composant (cf. `injectKtDialogOpener`). */
+    injectOpener<C>(component: ComponentType<C>, baseConfig?: KtDialogOpenerConfig<D, R, C>): (data: D, config?: KtDialogOpenerConfig<D, R, C>) => DialogRef<R, C>;
+}
+/**
+ * ✅ STRATÉGIE PAR DÉFAUT pour implémenter un dialog `@ktortu/aaa`. Toute nouvelle dialog DOIT être
+ * écrite ainsi. N'utilisez `injectKtDialogData` / `injectKtDialogOpener` directement QUE dans un cas
+ * avancé non couvert ici.
+ *
+ * Définit le contrat typé du dialog (données `D` + résultat `R`) en UN SEUL endroit, co-localisé avec
+ * le composant. Renvoie trois accès liés aux mêmes types — `injectData()` (données), `injectRef()`
+ * (référence dont `close()` n'accepte que `R`) et `injectOpener()` (ouvreur) — d'où l'impossibilité
+ * d'une divergence de type entre composant et ouvreur.
+ *
+ * Recette à copier pour CHAQUE dialog :
+ * 1. `interface XxxData { … }` (ou `void` si aucune donnée) ;
+ * 2. `const xxxDialog = defineKtDialog<XxxData, Résultat>();` ;
+ * 3. dans le composant : `injectData()` pour lire la donnée, `injectRef()` pour fermer avec résultat ;
+ * 4. `export const injectXxxDialog = () => xxxDialog.injectOpener(XxxDialog);` (co-localisé) ;
+ * 5. côté consommateur : `private readonly openXxx = injectXxxDialog();` (initialiseur de champ).
+ *
+ * Convention de fermeture : annuler / fermer SANS résultat via la directive `[ktDialogClose]`
+ * (→ `undefined`) ; renvoyer un résultat via `ref.close(résultat)` (typé `R`). Passer un résultat par
+ * `[ktDialogClose]="x"` reste possible mais N'EST PAS typé (la directive ignore `R`).
+ *
+ * @example
+ * ```ts
+ * // ─── rename-dialog.ts : composant + contrat + ouvreur, co-localisés ───
+ * export interface RenameData { currentName: string; }
+ *
+ * const renameDialog = defineKtDialog<RenameData, string>(); // D et R déclarés UNE seule fois
+ *
+ * @Component({
+ *   imports: [KtButton, KtDialogImports],
+ *   template: `
+ *     <h2 ktDialogTitle>Renommer</h2>
+ *     <footer ktDialogActions>
+ *       <button ktButton ktDialogClose>Annuler</button>            // ferme sans résultat (undefined)
+ *       <button ktButton (click)="submit()">Renommer</button>      // ferme avec résultat typé
+ *     </footer>`,
+ * })
+ * export class RenameDialog {
+ *   protected readonly data = renameDialog.injectData();  // RenameData garanti
+ *   private readonly ref = renameDialog.injectRef();      // DialogRef<string>
+ *   protected submit() { this.ref.close('nouveau-nom'); } // close(result?: string) — typé
+ * }
+ *
+ * export const injectRenameDialog = () => renameDialog.injectOpener(RenameDialog);
+ *
+ * // ─── consommateur ───
+ * private readonly openRename = injectRenameDialog();     // initialiseur de champ = contexte d'injection
+ * rename() {
+ *   this.openRename({ currentName: 'X' }).closed.subscribe(name => {
+ *     // name: string | undefined
+ *   });
+ * }
+ * ```
+ */
+declare function defineKtDialog<D = void, R = unknown>(): KtDialogContract<D, R>;
 
 declare class KtDialogContainer extends CdkDialogContainer implements OnInit {
     private readonly dialogRef;
@@ -318,5 +380,5 @@ declare class KtDialogContainer extends CdkDialogContainer implements OnInit {
  */
 declare const KtDialogImports: readonly [typeof KtDialogHeader, typeof KtDialogTitle, typeof KtDialogDescription, typeof KtDialogContent, typeof KtDialogActions, typeof KtDialogClose, typeof KtDialogFocusInitial, typeof KtDialogSheetHandle];
 
-export { KT_DIALOG_AAA_DEFAULTS, KtDialogActions, KtDialogClose, KtDialogContainer, KtDialogContent, KtDialogDescription, KtDialogFocusInitial, KtDialogHeader, KtDialogImports, KtDialogSheetHandle, KtDialogTitle, injectKtDialogData, injectKtDialogOpener, provideKtDialogDefaults, resolveKtDialogPanelClass };
-export type { KtDialogOpenerConfig, KtDialogPresentation };
+export { KT_DIALOG_AAA_DEFAULTS, KtDialogActions, KtDialogClose, KtDialogContainer, KtDialogContent, KtDialogDescription, KtDialogFocusInitial, KtDialogHeader, KtDialogImports, KtDialogSheetHandle, KtDialogTitle, defineKtDialog, injectKtDialogData, injectKtDialogOpener, provideKtDialogDefaults, resolveKtDialogPanelClass };
+export type { KtDialogContract, KtDialogOpenerConfig, KtDialogPresentation };