# ng-angular-popup

[![npm version](https://badge.fury.io/js/ng-angular-popup.svg)](https://badge.fury.io/js/ng-angular-popup)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Angular](https://img.shields.io/badge/Angular-18%2B-red)](https://angular.io)

A modern, lightweight, and highly customizable toast notification library for Angular 18+ applications with full support for signals, zoneless mode, and standalone components.

## ✨ What's New in v2.0.0

- 🎯 **Global Configuration via DI**: Configure all toast settings globally through `provideNgToast()`
- ⚡ **Pure CSS Animations**: No deprecated Angular animation APIs - works perfectly in zoneless mode
- 🎪 **Bouncy Spring Animations**: Beautiful enter and exit animations with spring physics
- 🎨 **Optional Icons**: Show/hide icons per toast or globally
- 📐 **Optimized Sizing**: Compact, professional design following modern web standards
- 📱 **Better Mobile Support**: Enhanced responsive design for all devices
- 🚀 **Angular 20 Ready**: Full support for Angular 18, 19, and 20

## Features

- 🚀 **Angular 18-20 Support**: Fully compatible with latest Angular versions
- ⚡ **Signals-based**: Uses Angular's signals API for reactive state management
- 🎯 **Zoneless Compatible**: Works perfectly without zone.js for maximum performance
- 🧩 **Standalone Components**: Fully supports Angular's standalone component architecture
- 🔄 **OnPush Change Detection**: Optimized performance
- 🎨 **Global Configuration**: Configure once, use everywhere via DI
- 📱 **Fully Responsive**: Mobile, tablet, and desktop optimized
- 🎪 **Smooth Animations**: Bouncy spring animations for enter/exit
- 🎯 **6 Positions**: top/bottom × left/center/right
- 🌈 **6 Toast Types**: Success, Error, Warning, Info, Primary, Secondary
- ⏱️ **Progress Bars**: Visual countdown indication
- 🖐️ **Dismissible**: Manual dismiss with animation
- 🖼️ **Optional Icons**: Show/hide icons per toast
- 🆕 **Modern Syntax**: Uses @for and @if control flow

## Installation

```bash
npm install ng-angular-popup
```

## Quick Start

### 1. Basic Setup (Zoneless Mode - Recommended)

```typescript
// app.config.ts
import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
import { provideNgToast } from 'ng-angular-popup';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideNgToast(),
  ]
};
```

### 2. Global Configuration (New in v2.0.0!)

Configure toast behavior globally:

```typescript
// app.config.ts
import { provideNgToast } from 'ng-angular-popup';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideNgToast({
      duration: 5000,              // Default 5 seconds
      position: 'top-right',       // Default position
      maxToasts: 3,                // Max 3 toasts at once
      width: 400,                  // Toast width in pixels
      showProgress: true,          // Show progress bar
      dismissible: true,           // Allow manual dismiss
      showIcon: true,              // Show icons
      enableAnimations: true       // Enable animations
    }),
  ]
};
```

### 3. Add Component to Template

```typescript
import { Component } from '@angular/core';
import { NgToastComponent, NgToastService, TOAST_POSITIONS, ToastPosition } from 'ng-angular-popup';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgToastComponent], // Import the component
  template: `
    <h1>My App</h1>
    <button (click)="showToast()">Show Toast</button>
    
    <!-- Add toast component (uses global config) -->
    <ng-toast></ng-toast>
  `
})
export class AppComponent {
  constructor(private toast: NgToastService) {}
  
  showToast() {
    // Uses global configuration
    this.toast.success('Operation successful!', 'Success');
  }
}
```

### NgModule (Legacy Support)

1. Import `NgToastModule` in your app.module.ts:

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { NgToastModule } from 'ng-angular-popup';

@NgModule({
  imports: [
    BrowserModule,
    BrowserAnimationsModule, // Required for animations
    NgToastModule
    // ...
  ]
})
export class AppModule { }
```

2. Add the toast component to your app.component.html:

```html
<ng-toast [position]="TOAST_POSITIONS.TOP_RIGHT" [width]="350"></ng-toast>
```

3. Inject and use the service in your components:

```typescript
import { NgToastService, TOAST_POSITIONS } from 'ng-angular-popup';

@Component({
  // ...
})
export class YourComponent {
  TOAST_POSITIONS = TOAST_POSITIONS; // Make positions available in template
  
  constructor(private toast: NgToastService) {}

  showSuccess() {
    this.toast.success('Success Message', 'Title', 3000);
  }

  showError() {
    this.toast.danger('Error Message', 'Error', 3000);
  }

  showInfo() {
    this.toast.info('Info Message', 'Information', 3000);
  }

  showWarning() {
    this.toast.warning('Warning Message', 'Warning', 3000);
  }
}
```

## API Reference

### Global Configuration Options

Configure via `provideNgToast()`:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `duration` | `number` | `3000` | Default duration in milliseconds |
| `position` | `ToastPosition` | `'bottom-right'` | Default toast position |
| `maxToasts` | `number` | `5` | Maximum toasts to display |
| `width` | `number` | `350` | Toast container width (px) |
| `showProgress` | `boolean` | `true` | Show progress bar by default |
| `dismissible` | `boolean` | `true` | Allow manual dismiss by default |
| `showIcon` | `boolean` | `true` | Show icons by default |
| `enableAnimations` | `boolean` | `true` | Enable animations |

### Toast Service Methods

All methods now support optional parameters that override global config:

| Method | Signature | Description |
|--------|-----------|-------------|
| `success()` | `(message, title?, duration?, showProgress?, dismissible?, showIcon?)` | Success toast |
| `danger()` | `(message, title?, duration?, showProgress?, dismissible?, showIcon?)` | Error toast |
| `info()` | `(message, title?, duration?, showProgress?, dismissible?, showIcon?)` | Info toast |
| `warning()` | `(message, title?, duration?, showProgress?, dismissible?, showIcon?)` | Warning toast |
| `primary()` | `(message, title?, duration?, showProgress?, dismissible?, showIcon?)` | Primary toast |
| `secondary()` | `(message, title?, duration?, showProgress?, dismissible?, showIcon?)` | Secondary toast |
| `removeToast()` | `(messageId: number)` | Remove specific toast |
| `clearAll()` | `()` | Remove all toasts |
| `setMaxToasts()` | `(max: number)` | Set max toasts |
| `getConfig()` | `()` | Get current config |

### Usage Examples

```typescript
// Use global config
this.toast.success('Saved!');

// Override specific options
this.toast.success('Saved!', 'Success', 5000, true, true, false); // No icon

// Without icon globally
provideNgToast({ showIcon: false });

// Persistent toast (no auto-dismiss)
this.toast.info('Important info', 'Notice', 0); // duration: 0

// Custom position per component
<ng-toast [position]="'top-right'" [width]="400"></ng-toast>
```

### Accessibility Features

- **High Contrast Colors**: All toast types use WCAG 2.1 AA compliant color combinations
- **Keyboard Navigation**: Dismissible toasts can be closed using keyboard
- **Screen Reader Support**: Proper ARIA attributes for screen readers
- **Focus Management**: Proper focus handling for interactive elements
- **Readable Text**: Optimized font sizes and weights for readability

### TOAST_POSITIONS

```typescript
// Available as a const object
const TOAST_POSITIONS = {
  TOP_LEFT: 'toaster-top-left',
  TOP_CENTER: 'toaster-top-center',
  TOP_RIGHT: 'toaster-top-right',
  BOTTOM_LEFT: 'toaster-bottom-left',
  BOTTOM_CENTER: 'toaster-bottom-center',
  BOTTOM_RIGHT: 'toaster-bottom-right'
} as const;

// Type for toast positions
type ToastPosition = typeof TOAST_POSITIONS[keyof typeof TOAST_POSITIONS];
```

## Styling and Customization

### Default Accessible Colors

The library uses a carefully selected color palette that meets WCAG 2.1 AA accessibility standards with proper contrast ratios:

| Toast Type | Border Color | Background Color | Text Color |
|------------|--------------|------------------|------------|
| Primary | #4338ca (Indigo) | #eef2ff (Indigo 50) | #111827 (Dark) |
| Secondary | #374151 (Slate) | #f1f5f9 (Slate 100) | #111827 (Dark) |
| Success | #047857 (Emerald) | #ecfdf5 (Emerald 50) | #111827 (Dark) |
| Info | #0369a1 (Cyan) | #ecfeff (Cyan 50) | #111827 (Dark) |
| Warning | #b45309 (Amber) | #fffbeb (Amber 50) | #111827 (Dark) |
| Danger | #b91c1c (Red) | #fef2f2 (Red 50) | #111827 (Dark) |

### Custom Styling

You can customize the toast appearance by overriding the CSS classes. Add your custom styles in your global styles file:

```scss
// Example customization
.toast-message {
  // Modify base toast styles
  border-radius: 12px;
  box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);
  
  // Customize specific toast types
  &.toast-success {
    border-left: 6px solid #047857;
    background-color: #ecfdf5;
  }

  &.toast-danger {
    border-left: 6px solid #b91c1c;
    background-color: #fef2f2;
  }

  &.toast-info {
    border-left: 6px solid #0369a1;
    background-color: #ecfeff;
  }
  
  &.toast-warning {
    border-left: 6px solid #b45309;
    background-color: #fffbeb;
  }
  
  // Customize toast content
  .msg-title {
    font-size: 1rem;
    font-weight: 600;
  }
  
  .msg-summary {
    font-size: 0.9375rem;
  }
  
  // Customize progress bar
  .toast-progress {
    height: 4px;
    opacity: 0.3;
  }
}
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Angular Version Compatibility

| Library Version | Angular Version | Features |
|----------------|------------------|----------|
| 2.0.0+         | Angular 18-20    | Signals, Zoneless, Global Config, Pure CSS Animations |
| 1.x.x          | Angular 12-17    | Basic features |

## Migration Guide (v1 → v2)

### Breaking Changes

1. **Minimum Angular Version**: Now requires Angular 18+
2. **Removed Deprecated APIs**: No longer uses deprecated Angular animation APIs
3. **Peer Dependencies**: Removed `@angular/animations` requirement

### Migration Steps

```typescript
// Before (v1)
import { provideAnimations } from '@angular/platform-browser/animations';
provideAnimations(), // No longer needed!
provideNgToast()

// After (v2) - Zoneless mode
provideZonelessChangeDetection(),
provideNgToast({
  // Optional global config
  duration: 5000,
  showIcon: true
})
```

### New Features in v2

- ✅ Global configuration via DI
- ✅ Optional icons (show/hide per toast or globally)
- ✅ Pure CSS animations (no deprecated APIs)
- ✅ Bouncy spring animations
- ✅ Better mobile/tablet support
- ✅ Optimized sizing

## Changelog

### v2.0.0 (2025-01-04)

**🎉 Major Release - Angular 18-20 Support**

- ✨ **NEW**: Global configuration via `provideNgToast(config)`
- ✨ **NEW**: Optional icons with `showIcon` parameter
- ✨ **NEW**: Pure CSS animations (zoneless compatible)
- ✨ **NEW**: Bouncy spring enter/exit animations
- 📐 **IMPROVED**: Optimized sizing for modern web standards
- 📱 **IMPROVED**: Better responsive design for mobile/tablet
- ⚡ **IMPROVED**: Full zoneless mode support
- 🔧 **CHANGED**: Minimum Angular version is now 18
- 🗑️ **REMOVED**: Deprecated Angular animation APIs
- 🗑️ **REMOVED**: `@angular/animations` peer dependency

### v1.0.0

- Initial release with Angular 12-17 support

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

Sashikumar Yadav

- Email: yshashi30@gmail.com
- GitHub: [@yshashi](https://github.com/yshashi)

## Support

If you like this project, please consider giving it a ⭐️ on [GitHub](https://github.com/yshashi/ng-angular-popup)!