ng-angular-popup/README.md

A modern, lightweight, and customizable toast notification library for Angular applications

# 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)

A modern, accessible, and highly customizable toast notification library for Angular applications. Now with full support for Angular v20, signals, and enhanced accessibility!

## Features

- 🚀 **Angular v20 Support**: Fully compatible with the latest Angular version
- ⚡ **Signals-based**: Uses Angular's signals API for reactive state management
- 🧩 **Standalone Components**: Fully supports Angular's standalone component architecture
- ♿ **Accessibility**: WCAG 2.1 AA compliant with proper contrast ratios and screen reader support
- 🎨 **Customizable**: Extensive styling options and configuration
- 📱 **Responsive**: Adapts perfectly to all screen sizes
- 🔧 **Easy Integration**: Simple API with both standalone and NgModule support
- 🎯 **Multiple Positions**: 6 different toast positions (top/bottom, left/center/right)
- 🌈 **Toast Types**: Success, Error, Warning, Info, Primary, Secondary
- ⏱️ **Progress Bars**: Visual indication of toast duration
- 🖐️ **Dismissible**: Optional manual dismiss functionality
- 🖥️ **Modern UI**: Clean, contemporary design with subtle animations

## Installation

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

## Quick Start

### Standalone Components (Angular 14+ recommended)

1. Configure the providers in your app.config.ts:

```typescript
import { ApplicationConfig } from '@angular/core';
import { provideAnimations } from '@angular/platform-browser/animations';
import { provideNgToast } from 'ng-angular-popup';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAnimations(), // Required for animations
    provideNgToast(),
    // other providers...
  ]
};
```

2. Import the component in your app.component.ts:

```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>Toast Example</h1>
    <button (click)="showSuccess()">Show Success Toast</button>
    <button (click)="showError()">Show Error Toast</button>
    
    <!-- Add the toast component to your template -->
    <ng-toast [position]="TOAST_POSITIONS.TOP_CENTER" [width]="350"></ng-toast>
  `
})
export class AppComponent {
  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);
  }
}
```

### 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

### Toast Service Methods

| Method | Parameters | Description |
|--------|------------|-------------|
| success | (message: string, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows a success toast |
| danger | (message: string, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows an error toast |
| info | (message: string, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows an info toast |
| warning | (message: string, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows a warning toast |
| primary | (message: string, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows a primary toast |
| secondary | (message: string, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows a secondary toast |
| toast | (message: string, type: ToastType, title?: string, duration?: number, showProgress?: boolean, dismissible?: boolean) | Shows a toast with specified type |
| removeToast | (messageId: number) | Removes a specific toast by ID |
| clearAll | () | Removes all toasts |
| setMaxToasts | (max: number) | Sets the maximum number of toasts to display at once |

### Toast Configuration

Toast messages can be configured with the following parameters:

```typescript
// Example usage with all parameters
toastService.success(
  'Operation completed successfully',  // message (required)
  'Success',                           // title (optional)
  5000,                                // duration in ms (optional, default: 3000)
  true,                                // showProgress (optional, default: true)
  true                                 // dismissible (optional, default: true)
);
```

### Toast Component Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| width | number | 350 | Width of the toast in pixels |
| position | ToastPosition | TOAST_POSITIONS.BOTTOM_RIGHT | Position of the toast notification |

### 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 |
|----------------|------------------|
| 1.0.0          | Angular 12-20    |
| 0.6.6          | Angular 12-17    |

## 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)!