// ===== README.MD =====

🍞 NG-Toast - Modern Angular Toast Library

Une bibliothèque de toast moderne et complète pour Angular 18+ avec support des signals, standalone components, et toutes les fonctionnalités avancées.

✨ Fonctionnalités

• 🎯 Angular 18+ avec Signals et Standalone Components
• 🎨 Design moderne avec animations fluides
• 🔧 Hautement configurable avec de nombreuses options
• 📱 Responsive et support RTL
• ♿ Accessible avec support ARIA
• 🎵 Sons de notification optionnels
• 🎭 5 types de toast (success, error, warning, info, loading)
• 📍 6 positions d'affichage
• 🎪 5 animations (slide, fade, bounce, zoom, flip)
• 🌙 Thèmes (light, dark, auto)
• ⚡ Performances optimisées avec OnPush et signals
• 🔄 Actions personnalisées avec boutons
• ⏸️ Pause au survol
• 📊 Barre de progression
• 🚫 Prévention des doublons
• 🔢 Limite de toasts affichés
• 📌 Toasts persistants

🚀 Installation

npm install @yourname/ng-toast

📦 Setup

1. Importer dans votre app :

// app.component.ts
import { Component, inject } from "@angular/core";
import { ToastService, ToastOutletDirective } from "@yourname/ng-toast";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [ToastOutletDirective],
  template: `
    <div class="app">
      <!-- Votre contenu -->

      <!-- Toast Outlet - OBLIGATOIRE -->
      <div ngToastOutlet></div>
    </div>
  `,
})
export class AppComponent {
  private toastService = inject(ToastService);
}

2. Ajouter les styles dans votre angular.json :

"styles": [
  "node_modules/@yourname/ng-toast/styles/toast.css"
]

Ou importer dans votre styles.scss :

@import "@yourname/ng-toast/styles/toast";

🎯 Usage de base

export class MyComponent {
  private toastService = inject(ToastService);

  showSuccess(): void {
    this.toastService.success("Opération réussie !");
  }

  showError(): void {
    this.toastService.error("Une erreur est survenue");
  }

  showWarning(): void {
    this.toastService.warning("Attention !");
  }

  showInfo(): void {
    this.toastService.info("Information importante");
  }

  showLoading(): void {
    const id = this.toastService.loading("Chargement...");

    // Simuler une opération async
    setTimeout(() => {
      this.toastService.dismiss(id);
      this.toastService.success("Terminé !");
    }, 3000);
  }
}

⚙️ Configuration avancée

// Configuration globale
constructor() {
  this.toastService.setGlobalConfig({
    position: 'top-right',
    duration: 4000,
    animation: 'slide',
    theme: 'dark',
    maxToasts: 5,
    preventDuplicates: true,
    pauseOnHover: true,
    showProgress: true,
    sound: true
  });
}

// Toast avec configuration personnalisée
showCustomToast(): void {
  this.toastService.show({
    type: 'success',
    title: 'Succès',
    message: 'Opération terminée avec succès',
    duration: 6000,
    position: 'bottom-center',
    animation: 'bounce',
    icon: '🎉',
    customClass: 'my-custom-toast',
    actions: [
      {
        label: 'Voir détails',
        action: () => this.showDetails(),
        style: 'primary'
      },
      {
        label: 'Fermer',
        action: () => console.log('Fermé'),
        style: 'secondary'
      }
    ]
  });
}

🎨 Personnalisation CSS

// Variables CSS personnalisables
:root {
  --ng-toast-success-bg: linear-gradient(135deg, #10b981 0%, #059669 100%);
  --ng-toast-error-bg: linear-gradient(135deg, #ef4444 0%, #dc2626 100%);
  --ng-toast-warning-bg: linear-gradient(135deg, #f59e0b 0%, #d97706 100%);
  --ng-toast-info-bg: linear-gradient(135deg, #3b82f6 0%, #2563eb 100%);
  --ng-toast-loading-bg: linear-gradient(135deg, #8b5cf6 0%, #7c3aed 100%);

  --ng-toast-border-radius: 8px;
  --ng-toast-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  --ng-toast-backdrop-filter: blur(10px);
}

// Classes personnalisées
.my-custom-toast {
  border: 2px solid gold;
  box-shadow: 0 0 20px rgba(255, 215, 0, 0.5);
}

// Toast spécifique
.ng-toast--success {
  background: var(--ng-toast-success-bg);
}

📍 Positions disponibles

• top-right (défaut)
• top-left
• top-center
• bottom-right
• bottom-left
• bottom-center

🎪 Animations disponibles

• slide (défaut)
• fade
• bounce
• zoom
• flip

🎭 Types de toast

• success ✅
• error ❌
• warning ⚠️
• info ℹ️
• loading ⏳

🔧 API du ToastService

Méthodes principales

// Afficher un toast
show(config: ToastConfig): string

// Méthodes de commodité
success(message: string, config?: Partial<ToastConfig>): string
error(message: string, config?: Partial<ToastConfig>): string
warning(message: string, config?: Partial<ToastConfig>): string
info(message: string, config?: Partial<ToastConfig>): string
loading(message: string, config?: Partial<ToastConfig>): string

// Gestion des toasts
dismiss(id: string): void
dismissAll(): void
clear(): void
pause(id: string): void
resume(id: string): void

// Configuration
setGlobalConfig(config: Partial<GlobalToastConfig>): void

Interface ToastConfig

interface ToastConfig {
  id?: string;
  type?: "success" | "error" | "warning" | "info" | "loading";
  title?: string;
  message: string;
  duration?: number;
  position?: ToastPosition;
  animation?: ToastAnimation;
  theme?: "light" | "dark" | "auto";
  dismissible?: boolean;
  pauseOnHover?: boolean;
  showProgress?: boolean;
  icon?: string;
  customClass?: string;
  actions?: ToastAction[];
  data?: any;
  sticky?: boolean;
  rtl?: boolean;
  sound?: boolean;
  priority?: number;
}

🎯 Exemples avancés

Toast avec actions

showConfirmationToast(): void {
  this.toastService.info('Voulez-vous sauvegarder les modifications ?', {
    title: 'Confirmation',
    sticky: true,
    actions: [
      {
        label: 'Sauvegarder',
        action: () => this.save(),
        style: 'primary'
      },
      {
        label: 'Annuler',
        action: () => console.log('Annulé'),
        style: 'secondary'
      },
      {
        label: 'Supprimer',
        action: () => this.delete(),
        style: 'danger'
      }
    ]
  });
}

Toast de chargement avec mise à jour

async processData(): Promise<void> {
  const loadingId = this.toastService.loading('Traitement en cours...');

  try {
    await this.dataService.process();
    this.toastService.dismiss(loadingId);
    this.toastService.success('Données traitées avec succès !');
  } catch (error) {
    this.toastService.dismiss(loadingId);
    this.toastService.error('Erreur lors du traitement');
  }
}

Toast avec données personnalisées

showOrderToast(order: Order): void {
  this.toastService.success(`Commande #${order.id} créée`, {
    title: 'Nouvelle commande',
    data: order,
    actions: [
      {
        label: 'Voir commande',
        action: () => this.router.navigate(['/orders', order.id])
      }
    ]
  });
}

🌐 Support RTL

// Configuration RTL globale
this.toastService.setGlobalConfig({
  rtl: true,
});

// Toast RTL spécifique
this.toastService.info("رسالة باللغة العربية", {
  rtl: true,
});

♿ Accessibilité

La bibliothèque respecte les standards d'accessibilité :

• Support ARIA avec role="alert"
• aria-live adapté selon le type
• Navigation au clavier
• Contrastes respectés
• Support des lecteurs d'écran

🎵 Sons de notification

// Activer les sons globalement
this.toastService.setGlobalConfig({
  sound: true,
});

// Son pour un toast spécifique
this.toastService.success("Message", {
  sound: true,
});

📱 Responsive

Les toasts s'adaptent automatiquement aux écrans mobiles :

• Largeur ajustée sur petit écran
• Positions centrées sur mobile
• Touch-friendly

🔄 Migration

Depuis une autre bibliothèque

// Avant (autre lib)
this.toastr.success("Message");

// Après (ng-toast)
this.toastService.success("Message");

🐛 Dépannage

Toast non visible

1. Vérifiez que ToastOutletDirective est importé
2. Assurez-vous que <div ngToastOutlet></div> est présent
3. Vérifiez le z-index (défaut: 9999)

Styles non appliqués

1. Importez les styles dans angular.json ou styles.scss
2. Vérifiez les conflits CSS
3. Utilisez customClass pour forcer des styles

Performances

1. Limitez le nombre de toasts avec maxToasts
2. Utilisez preventDuplicates: true
3. Évitez les toasts avec duration: 0 sans dismiss manuel

📄 Licence

MIT © Votre Nom

🤝 Contribution

Les contributions sont les bienvenues ! Voir CONTRIBUTING.md.

📋 Changelog

Voir CHANGELOG.md pour l'historique des versions.

💝 Support

Si cette bibliothèque vous aide, n'hésitez pas à lui donner une ⭐ !

Pour les questions et support : GitHub Issues